Skip to main content

Architecture

A Bun and Hono service on Cloud Run. It reads products from the Shopify Admin API on each request and has no database.

Request flow​

  1. API Gateway forwards /cartographer/* to the service. Cloud Run only accepts calls from the gateway.
  2. Key check: the service confirms the caller's API key with the gateway's authorizer. A missing key gets 401 and a rejected key is refused. If the authorizer can't be reached, the request fails with 503 rather than being let through.
  3. Routes load the variant and its product from Shopify and apply the rules below.

Every request has a 10-second limit.

Standard vs Rush Production​

The variant's Estimated Arrival option decides how it's treated:

Estimated ArrivalTreated asCart line gets
Standard ProductionMade-to-orderProduction and delivery date properties
Rush ProductionReady to shipReady-to-ship properties, plus a separate rush-fee line

Rush fee​

The rush-fee line uses a variant of the rush-fee-v2 product, which has one variant per price. The price comes from the product's custom.rush_fee metafield, or the default when it has none.

When the caller waives the fee, the line is still added: at full price with a 100% discount in Admin format, or as the $0 variant in Storefront format. Deciding who qualifies is up to the caller.

Delivery estimates​

Dates come from production days plus a delivery window. Product metafields set them per product, with environment defaults as the fallback (see Integrations). Dates are worked out on the UTC calendar day, so the server's timezone doesn't change them.

GET /estimates returns one row per Estimated Arrival option the product has, using the same rules as POST /lines, so a preview always matches what goes in the cart.

Replacements​

GET /replacements compares the requested variant with its sibling that differs only by Estimated Arrival, and grades each against the wedding date:

Days to spareFit
14 or moreComfortable
0 to 13Tight
Under 0Too late

A Rush option that's too late becomes expedite if expedited shipping would still arrive by the wedding.

The recommendation is:

  1. Rush, when Standard has under 7 days to spare and Rush can be bought and fits.
  2. Otherwise the first option that can be bought and fits, starting with the requested variant.
  3. Otherwise an expedite option.

Without a wedding date, the recommendation is the first option that can be bought.