Skip to main content

Architecture

A Bun and Hono service on Cloud Run. It has no database: product data is read live from Shopify on each request, and slower-changing reference data is cached in memory.

Request flow​

  1. API Gateway forwards /catalog/* 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 validate the query, call Shopify, Airtable or BigQuery, and shape the response.

Every request has a 10-second limit and returns 504 past it. Calls to Shopify, Airtable and BigQuery are retried within that limit.

Where data comes from​

Endpoint groupSource
Products (all, rush, standard)Shopify, live
Colors and color familiesAirtable's color taxonomy, narrowed to colors in use on Shopify
Sizes, fabrics, typesShopify's product filters
Expected size rangeAirtable
Back-in-stock datesPurchase order dates and inventory from the BigQuery warehouse, joined to Shopify products by SKU

The warehouse only holds production data, so staging computes the same back-in-stock dates as production.

Caching​

Airtable taxonomy and BigQuery results are cached in memory and refreshed in the background once they're old:

  • Callers get the cached copy right away, even while a refresh is running.
  • If a refresh fails, the last good copy keeps being served and a Serving stale taxonomy warning is logged.
  • Taxonomy caches are also saved to Cloud Storage, so a fresh instance starts from the last copy instead of waiting on Airtable.
  • Caches are loaded when an instance boots.

Shopify product data is never cached.

Swatch images​

Color swatch URLs point at Birdy Grey's CDN, which fetches the image from Airtable on first request and keeps it.