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β
- API Gateway forwards
/catalog/*to the service. Cloud Run only accepts calls from the gateway. - Key check: the service confirms the caller's API key with the gateway's authorizer. A missing key gets
401and a rejected key is refused. If the authorizer can't be reached, the request fails with503rather than being let through. - 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 group | Source |
|---|---|
| Products (all, rush, standard) | Shopify, live |
| Colors and color families | Airtable's color taxonomy, narrowed to colors in use on Shopify |
| Sizes, fabrics, types | Shopify's product filters |
| Expected size range | Airtable |
| Back-in-stock dates | Purchase 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 taxonomywarning 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.