# Storefront Flows (Lightweight Addendum)

## Scope of this document

`01-information-architecture.md` and `02-core-user-flows.md` cover the **merchant admin** only. Neither Phase 2 nor Phase 4 (`../design/`) covered the **customer-facing storefront** — this was flagged as a real gap in `../design/06-open-questions.md` #1.

This document resolves the part of that gap that blocks forward progress: it gives Phase 5's checkout orchestration (Commerce Core) a concrete flow shape to build against. **It deliberately does not do everything a full storefront IA/design pass would do** — no visual design, no page-by-page layout, no resolution of the merchant-theming question (how much of the storefront's look a merchant can customize). Those remain deferred to a dedicated storefront design phase, per the decision recorded in `../design/06-open-questions.md`.

## The five storefront flows

### 1. Browse & discover

Customer arrives at the storefront (home, a category page, or a direct product link) and finds products via category navigation or search. Search is powered by Search Engine (`../architecture/04-domain-modules.md`); category/collection browsing is powered by Catalog. No cart or account interaction required at this stage.

### 2. Product detail

Customer views a single product: images, description, price, variant selection (size/color), and stock availability. If the selected variant is unavailable, this is where a "notify me when back in stock" affordance appears (Automation Engine's back-in-stock detection, `../architecture/04-domain-modules.md` module 11, surfaced to the customer via Notification Service once they opt in). Related/complementary product suggestions (from the automation catalog in `../architecture/01-product-vision.md`) surface here, below the primary product content — never blocking the primary "add to cart" action.

### 3. Cart

Customer reviews selected items, adjusts quantity, or removes items. Cart state is session-scoped (per `../system/02-module-schemas.md`'s note that Commerce Core holds checkout state in-memory/session-scoped, not as its own persisted entity) until checkout begins. Stock is soft-reserved only once checkout starts (step 4), not merely by being in a cart — an item sitting in a cart doesn't lock inventory away from other customers. If a cart sits inactive past a threshold, this is what Automation Engine's abandoned-cart detection (`../ux/02-core-user-flows.md` #4) later acts on.

### 4. Checkout

A single linear sequence, deliberately **not customizable by the merchant in step order or step count** — per "simplicity before flexibility" (`../architecture/02-principles-and-tradeoffs.md`), checkout is the one place CommerceDex is maximally opinionated, even though visual theming may vary by merchant:

1. **Contact** — email (or account login/guest choice).
2. **Shipping address** — with address validation; Shipping calculates available methods/rates for the entered address (Shipping module).
3. **Shipping method** — customer selects from the rates returned in step 2.
4. **Payment** — customer enters payment details, handled by the connected gateway (Payments module never touches raw card data, per `../architecture/06-open-questions.md` #4). Tax is calculated and shown at this stage once address and items are known (Tax module, provider-agnostic interface per `../system/02-module-schemas.md`).
5. **Review & place order** — final order summary (subtotal, discount if a code was applied, tax, shipping, total) before the customer commits. This is the one explicit confirmation step in the entire flow — everything before it is freely editable without friction, consistent with `../ux/03-ux-patterns-and-conventions.md` rule 3 (confirmation reserved for the actual money-committing action).

Placing the order is the transaction boundary described in `../architecture/05-module-interaction-model.md`'s worked example and made concrete in `../system/03-event-and-job-system.md`: Commerce Core orchestrates Tax, Discount Engine, Payments, and Inventory synchronously, Orders persists the order, and the `order.placed` event fans out to every subscriber from there.

### 5. Order confirmation

Customer sees an order confirmation (order number, summary, estimated delivery if applicable) and receives a confirmation notification — the customer-facing side of `../ux/02-core-user-flows.md` #3 (Order lifecycle), which continues in the admin from this point on.

## What's still deferred

- **Visual design of every page above** — layout, componentry, and the design tokens a storefront would use (which may differ from `../design/02-design-tokens.md`, built for the admin operator tool, not a public sales surface).
- **Merchant theming** — how much of the storefront's appearance a merchant can customize without it becoming "a website builder" (`../architecture/01-product-vision.md`'s explicit anti-goal). This needs its own resolution, not an assumption either way.
- **Storefront information architecture beyond these five flows** — e.g., account/order-history pages for returning customers, wishlist pages, content pages (Content Manager output) woven into storefront navigation.

These remain open for a dedicated storefront design phase, not silently resolved by this addendum.