System map

The architecture and the two boundaries that must always hold.

The boundary between the storefront and the Shop API is recorded in ADR-0001 (docs/adr/ in the repository); terms such as storefront-only capability and shared capability are defined in the repository’s CONTEXT.md.

The diagram records the existing deployment configuration, including shop.sandrino.run for the storefront. https://tarnandtimber.com is the intended storefront address for a later cutover; changing the brand does not change live domains, authentication audiences or infrastructure resource names.

Architecture

Read the diagram from the clients on the left. Browsers and operators reach their own apps. MCP clients reach the MCP server with a bearer token. Requests for shared capabilities end at the API; requests for capabilities only the storefront performs end at the storefront, which is bound to the same commerce database. The API also runs the Stripe webhook and the hourly jobs.

Rules the diagram encodes

Domain execution (carts, orders, payments, workflows) and the commerce database belong to two Workers: the API and the storefront. The storefront runs the capabilities only it performs through the same domain operations, from server-only modules, against the same database and AccountWriter; shared capabilities stay in the API and the storefront calls their public endpoints. The MCP server has no database binding. The backoffice keeps its own database for operator sessions and audit and has no access to the shop’s.
The storefront keeps OAuth redirects, cookies, Stripe Elements, WebMCP registration and all My Account calls. Those are protocol and identity concerns, not shop business logic.
The Auth0 proxy issues credentials and answers introspection; it never forwards shop business requests to the API or MCP server.
The MCP server holds no state and no business rules. It authorizes tools, exchanges tokens, calls the API and formats results.

Two boundaries that must always hold

1. The Auth0 proxy is an extension of Auth0

It fronts the Auth0 custom domain, runs the Poppy sign-in flows, grants, sessions and Custom Token Exchange, and serves discovery, introspection and revocation. It issues and brokers credentials. It never forwards resource traffic.

2. My Account is web-only

Auth0’s My Account API is called only by the storefront, with the customer’s own My Account token. The Shop API has no My Account endpoints and never receives a My Account token.

The Auth0 proxy never proxies the API or MCP

No Auth0 proxy route forwards to api.tarnandtimber.com, mcp.tarnandtimber.com or the storefront’s resource paths, and none is ever added. Poppy agents call the API and the MCP server directly with a token, exactly as every other client does; Poppy discovery advertises those URLs. The Auth0 proxy’s boundary test (apps/proxy-auth0/src/app.boundary.test.ts) sends every method to the old Poppy, MCP and conversation paths and checks that no request leaves for those hosts. The API and MCP server call the Auth0 proxy to introspect Sessions, and the Auth0 proxy calls the API only for its internal notifications (signed-out Sessions, connected agents, agent authorization), authenticated by X-Proxy-Auth0-Secret.

My Account stays in the storefront

That covers authentication methods, passkeys, MFA enrollment and removal, and recovery codes. My Account tokens stay in the storefront’s server-side session. See My Account.

Where to go next

Components describes each box in the diagram.
Callers and tokens explains how the API tells callers apart.
Request flows walks through real requests step by step.

Diagnostic ownership

ShopDatabase also retains five diagnostic tables; it is not a new database or collector. BackofficeDatabase continues to own only operator sessions and the separate access ledger. “No shop database access” means no direct binding: auditors can investigate authorized diagnostics through API procedures. Storefront, MCP and backoffice emit through distinct named private API producer capabilities; the Auth0 proxy emits only synthetic HTTP streams, without app recorder or database access. Genuine direct/forwarded Auth0 events remain visibly separate from simulation. See diagnostic investigations for actual service/runtime attribution, source evidence, bounded raw demo policy and 30-day retention/restore behavior.