Storefront

Storefront is the customer-facing half of our multitenant e-commerce platform. A single deployment serves every merchant we host: each tenant gets its own subdomain (acme.shop.example.com, globex.shop.example.com), its own catalog, pricing and branding, but all tenants share one application instance and one set of database tables.

We are mid-migration. The storefront is moving from the Pages Router to the Next.js 15 App Router route by route, and client state is moving off Redux + redux-saga onto TanStack Query. New routes are expected to be written App-Router-first; the old Pages Router code is being retired as each surface is ported.

Layout

Path	What lives there
app/	App Router routes. app/[tenant]/… is the per-merchant storefront.
lib/	Shared server-side helpers: tenant resolution, session, data access.

Local development

npm install
npm run dev

The dev server runs on localhost:3000. To work against a specific tenant, add an entry to your hosts file (e.g. acme.localhost) and browse to http://acme.localhost:3000.

Conventions

• Server Components are the default; 'use client' is a deliberate choice, not a habit.
• Anything under lib/ that touches the database or the session is server-only.
• Money is stored and passed around as integer minor units (priceCents).
• Dates are UTC on the wire, localised at the edge of the UI.
• Prefer async/await over .then() chains.
• Every PR needs a description that explains the why, not just the what.

Testing

npm test runs the Vitest suite. Unit tests are expected on anything that writes data. We do not currently have integration coverage on the storefront — that gap is tracked in PLAT-4471.