Commerce Platform

The hard requirement was multi-tenancy. One admin instance owns N stores, and every single query, route handler and webhook has to be scoped so that store A can never read or mutate anything belonging to store B. Getting this wrong is not a rendering bug — it is a data breach.

The second hard requirement was payment correctness. Stripe does not promise to deliver a webhook exactly once. It promises at least once. If the handler is written naively, the same `checkout.session.completed` event arrives twice and the customer gets two orders for one payment.

Store scoping is structural rather than remembered. The store id is a route parameter, every data access is resolved through it, and there is no code path that queries a product without also constraining it to a store. Making the safe thing the only thing available is more reliable than making it the thing you have to remember.

The webhook handler verifies the Stripe signature, then treats the event id as the unit of work — an event that has already been processed is acknowledged and discarded rather than replayed. The order write is keyed so that a duplicate delivery cannot create a second order.

On the storefront, cart state lives in Zustand and persists across reloads, with SWR handling product data. The split matters: the cart is client-owned and must survive a refresh; the catalogue is server-owned and must stay fresh. Those are different problems and they get different tools.

Because they have different jobs. The admin is authenticated, write-heavy, and only a handful of people ever load it — its bundle size barely matters. The storefront is public, read-heavy, and its load time is directly a conversion number.

Keeping them separate means the storefront ships almost no admin code, and the admin can grow without making the storefront slower. It also means a new client gets a new storefront deployment rather than a new fork of everything.