HEIR, fragrance store.

The storefront is Next.js 15 on the App Router, reading Shopify through the Storefront API and writing through the Admin API. Nothing about the catalogue is hardcoded: products, collections, blog articles and the shop's localisation all come from Shopify at request time.

Every Shopify read is wrapped in Next's use cache with a tag and a lifetime, so product and collection queries are cached for days and localisation for hours. A Shopify webhook hits /api/revalidate, which calls revalidateTag for products or collections — the client edits a price in the admin and the site follows without a deploy.

Shop filters are driven by a naming convention rather than code. Collections whose handle starts with collection- become the category filters and ones starting with family- become the olfactive families — Ambery Oud, Aromatic Woody, Floral Fruity Musk, Fruity Floral, Oriental Gourmand. Adding a sixth family is a new collection in Shopify, not a release.

Product pages are assembled from Shopify metafields and metaobjects: notes_accords, perfumer, ingredients, product_details, shipping_information, return_policy. The accordion on a product page is built from whatever metafields exist, with defaults underneath, so a product with no perfumer note renders cleanly instead of leaving a gap.

Pricing is multi-market. Middleware reads Vercel's x-vercel-ip-country header into a country cookie, the switcher writes a country_override cookie that always wins, and both feed Shopify's @inContext directive. The country list and currencies come from Shopify's Markets settings at runtime, so a new market is a dashboard change.

Markets cost cache entries, so I collapse them. Prices only vary by currency, and sending all thirty-odd countries to @inContext would multiply the product cache for identical results — pricingCountryFor picks one representative country per currency so they share an entry. The cart still uses the visitor's real country, where shipping and tax genuinely differ.

Login is email OTP through Supabase, on HEIR's own pages, and the Shopify customer is created behind it. /api/auth/complete-signup searches Shopify by email, falls back to searching by phone when Shopify rejects a duplicate number, then retries without the phone — Shopify treats customer phone numbers as unique and the signup form should not dead-end because of it.

A user_mappings table in Supabase joins the Supabase auth user to the Shopify customer id, with partial indexes on email, phone and user id filtered to is_active = true. The Shopify webhook keeps it honest: customers/create fills in the Shopify id on a pending row, customers/update syncs name and email, and customers/delete soft-deletes rather than dropping the row, so a deletion in Shopify never silently orphans a login.

The webhook verifies Shopify's HMAC-SHA256 signature against SHOPIFY_WEBHOOK_SECRET before it parses the body, and Indian phone numbers are normalised to +91 on the way in, because the same number arrives from Shopify in several shapes.

Reviews are Judge.me, read server-side by product handle and folded into the product page's Product JSON-LD as aggregateRating, but only when there is at least one review — Google drops the whole rich result for an empty rating. ATLAS currently shows 4.8. Customers can upload up to five photos per review; those go to a Supabase storage bucket behind a login check and a rate limit.

Public endpoints sit behind Upstash Redis sliding windows, tightest on the unauthenticated user-check route, because it is the one an attacker could use to enumerate phone numbers and every attempt costs a database query. If Upstash is not configured the limiters return null and the site still runs, which keeps local development simple.

Two Vercel cron jobs: /api/reconcile at 02:00 daily counts failed events and pending or failed customer mappings so drift is visible instead of discovered by a customer, and /api/keep-alive on Mondays and Thursdays pings Supabase so the project is not paused for inactivity. The admin monitor page at /account/admin reads the same failed-events table, gated on a single ADMIN_EMAIL match.

The whole site could be locked pre-launch. Setting SITE_PASSWORD makes middleware redirect everything except the unlock route to /site-locked, so HEIR could share the real domain with photographers and the perfumer before the collection was public. Unsetting it opens the site.