diff --git a/specs/SD-0001-mvp-sign-up-and-single-storefront.md b/specs/SD-0001-mvp-sign-up-and-single-storefront.md deleted file mode 100644 index 087d178..0000000 --- a/specs/SD-0001-mvp-sign-up-and-single-storefront.md +++ /dev/null @@ -1,1059 +0,0 @@ -# Solution Design: ecomm MVP — sign up and create a single storefront - -| | | -| --- | --- | -| **Anchor** | [wiggleverse/wiggleverse-ecomm#1](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/1) (`type/feature`, `priority/P1`) | -| **Author(s)** | Claude (session ecomm-0020), for Ben Stull | -| **Reviewers / approvers** | Ben Stull | -| **Status** | `approved` | -| **Version** | v0.2.0 | -| **Source artifacts** | BDD corpus: [research/shopify](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify) (esp. [flows/first-run-experience.md](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify/flows/first-run-experience.md)) · Prototype: [wiggleverse-ecomm-prototype](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype) (R01–R07) · Reference: Shopify first-run experience · Supersedes: — | - -**Change log** - -| Date | Version | Change | By | -| --- | --- | --- | --- | -| 2026-06-10 | v0.1.0 | Initial draft (session ecomm-0020) | Claude | -| 2026-06-10 | v0.2.0 | Self-review fixes; status → `approved` under the session's autonomous posture (handbook §6.5) — operator amendments welcome as v0.2.x | Claude | - ---- - -## 1. Business Context - -*The business lens — solution-agnostic throughout. No mechanism is proposed until §2.* - -### 1.1 Executive Summary - -Independent merchants who want to sell online need a commerce platform that -treats them honestly — and today Wiggleverse has nothing to offer them: no way -to exist on the platform, no storefront to own, no surface to manage. This -design delivers the first real value of ecomm: a person can become a merchant — -establish their identity, claim their one storefront, and stand on a stable -management surface — in every environment the platform runs in, from day one. -The beneficiaries are the first merchants (who can finally exist on the -platform) and the ecomm line itself (every subsequent capability — catalog, -orders, checkout — gains a real account-and-storefront spine to attach to, -instead of mocks). Just as importantly, it proves the platform can be brought -to life anywhere from nothing: a fresh, empty environment reaches "first -merchant, first storefront" through the product alone, with no hand-seeded -data — so launching the real service is an ordinary, rehearsed act rather than -a one-off ritual. - -### 1.2 Background - -ecomm is Wiggleverse's multi-tenant, OHM-grounded alternative to Shopify — a -commerce platform whose mechanics are accountable to the -[OHM concept corpus](https://ohm.wiggleverse.org) (no dark patterns, data -minimization, durable addressability, honest pricing). The product was explored -in a first-pass prototype (`wiggleverse-ecomm-prototype`, releases R01–R07, -189 scenario-bound tests) built against a harvested corpus of ~1,238 BDD -scenarios describing Shopify's behavior. That prototype is read-only prior art; -`wiggleverse-ecomm` is the clean greenfield rebuild, stood up 2026-06-10 with -its architecture intentionally undecided until this design. - -The strategic moment: the rebuild has repos, an issue tracker, and a charter — -but no app code and no users. Everything in the product line queues behind one -question: *how does a person come to exist on the platform and own a -storefront?* Until that is answered for real — against real persistence, in -real environments — no other capability can ship honestly. - -### 1.3 Business Actors / Roles - -| Role | Responsible for (in the business) | -| --- | --- | -| **Merchant** | A person running a (small) commerce business who wants to sell under their own storefront: they decide to join a platform, establish their business presence on it, and manage that presence over time. | -| **Platform operator** | The person/org running the ecomm service itself: stands up and maintains the environments the platform runs in, and is accountable for the service being available to merchants. | -| **ecomm team** | Builds the platform; needs each capability to rest on real, shippable foundations rather than mocks. | - -(Shoppers — the merchants' customers — are deliberately *not* an actor in this -design; nothing here is shopper-facing yet. See §1.7.) - -### 1.4 Problem Statement - -A person cannot become a merchant on ecomm. There is no way to establish an -identity on the platform, no way to claim a storefront, and no surface from -which to manage one — the platform has no users because it cannot have users. -And even if it could, there is today no defined path from "fresh, empty -environment" to "working platform serving its first merchant": local -development, pre-production, and production bring-up are all undefined, so -nothing built on top can ever actually launch. - -### 1.5 Pain Points - -| # | Pain | Who feels it | Cost / frequency today | -| --- | --- | --- | --- | -| PP-1 | No way to establish an identity on the platform — a would-be merchant simply cannot exist on ecomm. | Merchant | Total exclusion; blocks every merchant, always. | -| PP-2 | No way to own a storefront or reach a management surface — even an identity would have nothing to hold. | Merchant | Total; there is no unit of "my business" on the platform. | -| PP-3 | Every subsequent capability (catalog, orders, checkout, policies) has nowhere real to attach — work would have to build on mocks and be redone. | ecomm team | Blocks the entire product line; rework risk on everything shipped against fakes. | -| PP-4 | No defined, repeatable path from an empty environment to a working platform — bring-up of dev, pre-prod, and prod is folklore. | Platform operator | The service cannot launch anywhere; every environment question is open-ended toil. | - -### 1.6 Targeted Business Outcomes - -| Outcome | Success metric | Baseline → Target | Guardrail (must not regress) | How / when measured | -| --- | --- | --- | --- | --- | -| Merchants can exist on the platform | A real person can go from stranger to merchant-with-storefront, unaided | impossible → possible in every environment | No dark patterns at the door: no trial clock, no payment demand, no plan wall (OHM: Agency & Anti-Manipulation) | Walk the flow end-to-end in each environment at release | -| The product line is unblocked | Subsequent Features attach to a real account + storefront spine | everything mocked → nothing mocked | The spine doesn't need rework to host the next Feature (no throwaway auth/tenancy) | First post-MVP Feature builds on it without spine changes | -| Launching anywhere is routine | A fresh, empty environment reaches "first merchant signs up and creates the first storefront" through the product flows alone | folklore → documented, rehearsed gesture | Zero hand-seeded data in any environment | Bootstrap rehearsal executed on pre-prod, then prod, at release | - -### 1.7 Scope (business) - -- **In scope:** a person establishing an identity on the platform (joining and - returning); a merchant establishing their one storefront; the merchant - standing on a stable management surface for it; the platform being - bring-up-able from empty in every environment it runs in (local development, - pre-production, production). -- **Out of scope (later designs):** anything sold or bought — catalog, orders, - checkout, payments; the shopper-facing public storefront; teams/staff - (anyone besides the one merchant touching the storefront); plans, billing, - or any commercial relationship between merchant and platform; storefront - settings/management beyond simply *having* the surface. -- **Non-goals:** gating who may join (the prototype admitted users by - invitation; ecomm is an open product — anyone may become a merchant, and - re-introducing an admission gate is explicitly not pursued); supporting more - than one storefront per merchant *in this design* (the business wants the - door left open, not the capability now). - -### 1.8 Assumptions · Constraints · Dependencies - -- **Assumptions:** - - One storefront per merchant is the right *experience* bar for the MVP; - multiple-storefront merchants are a future need, not a current one. Risk - if wrong: an early merchant genuinely needs a second storefront — accepted; - the data is designed to keep that door open (Feature #1 constraint; INV-4). - - Merchants are reachable by email and will complete an email-based step to - join. Risk if wrong: an entry channel rethink — accepted at MVP scale. -- **Constraints:** - - OHM-groundedness is a charter constraint: entry must be honest — no - manufactured urgency, no data collected beyond need, no lock-in mechanics. - - The three environments are a constraint, not a stretch goal: Feature #1's - acceptance says no environment is "later". - - Wiggleverse engineering standards apply (handbook): provisioning and - deploy via flotilla (§8), secrets never in repos or transcripts (§6.3), - private repos by default (§5.5). -- **Dependencies:** - - **flotilla / launch-app** for environment provisioning and deploy (the - operator-run front door, handbook §8.5) — needed when the pre-prod and - prod environments are stood up. - - An **email delivery channel** for the entry step in real environments — - needed by the production-readiness slice (§7). - -### 1.9 Business Use Cases - -**BUC-1 — As a merchant, I can establish my identity on the platform, so that I can begin doing business there.** - -```gherkin -Scenario: BUC-1 — A stranger becomes known to the platform - Given a person who has never dealt with the platform - When they present themselves and prove who they are - Then the platform knows them as a returning individual from then on - And they were asked for nothing beyond what proving who they are required -``` - -```gherkin -Scenario: BUC-1a — A person who cannot prove who they are is not admitted as someone else - Given a person presenting an identity they cannot prove - When their proof fails - Then the platform does not mistake them for the claimed identity - And the genuine owner of that identity is unharmed -``` - -- **BUC-1 acceptance criteria:** the same person, returning later, is - recognized as the same merchant; two different people are never conflated; - no personal data beyond the minimum was demanded (OHM: Privacy & Data - Minimization). - -**BUC-2 — As a returning merchant, I can resume my standing on the platform, so that my business presence persists beyond a single visit.** - -```gherkin -Scenario: BUC-2 — A known merchant returns - Given a merchant the platform already knows - When they return and prove who they are - Then they resume exactly the standing they had — same identity, same storefront -``` - -- **BUC-2 acceptance criteria:** returning costs only the proof-of-identity - step; nothing about their standing is lost or reset. - -**BUC-3 — As a merchant, I can establish my storefront, so that my business has a presence of its own on the platform.** - -```gherkin -Scenario: BUC-3 — A merchant claims their storefront - Given a merchant known to the platform who has no storefront yet - When they establish their storefront - Then the platform holds exactly one storefront that is theirs - And establishing it cost them nothing and committed them to nothing -``` - -```gherkin -Scenario: BUC-3a — One storefront is the bar - Given a merchant who already has their storefront - When they deal with the platform - Then they are never led toward acquiring a second one -``` - -- **BUC-3 acceptance criteria:** every merchant who completes the step has - exactly one storefront; no payment, plan, or commitment was demanded - (corpus: 14.01.0015, 14.01.0016); the platform's books would still be - correct if a merchant were someday allowed several (the 1-1 bar is an - experience rule, not a law of the data — Feature #1 constraint). - -**BUC-4 — As a merchant, I can stand on a management surface for my storefront, so that everything I will later do for my business has a home.** - -```gherkin -Scenario: BUC-4 — The merchant arrives at their storefront's home - Given a merchant with a storefront - When they return to the platform - Then they arrive directly at their storefront's management surface - And it is honestly empty — it claims no capability that does not exist yet -``` - -- **BUC-4 acceptance criteria:** arrival is direct (no dead ends, no limbo — - a merchant *without* a storefront is guided to establish one instead, never - stranded); the surface carries the storefront's identity and nothing - fabricated. - -**BUC-5 — As a platform operator, I can bring the platform to life in a fresh environment, so that merchants can be served there without any hand-built state.** - -```gherkin -Scenario: BUC-5 — An empty environment reaches its first merchant - Given a brand-new environment with empty persistence - When the operator performs the documented bring-up gesture - And the first merchant walks the ordinary product flows - Then the environment serves that merchant a working storefront - And no data was placed by hand at any step -``` - -```gherkin -Scenario: BUC-5a — Bring-up is rehearsable - Given the bring-up gesture documented for one environment - When it is performed in the next environment (dev → pre-prod → prod) - Then it is the same gesture, and day-one production is simply the bootstrap state -``` - -- **BUC-5 acceptance criteria:** bring-up is a repeatable, documented gesture - (not folklore); it holds identically in local development, pre-production, - and production; the first merchant arrives through the product flows alone. - ---- - -## 2. Solution Proposal - -**Build the first vertical slice of the ecomm web application** — a -multi-tenant modular monolith that carries forward the prototype's *proven* -shape and inverts its *disqualifying* assumption: - -- **Carry forward** (validated by R01–R07 of the prototype): a four-layer - Python backend (`entrypoint → api → domains → platform`) with the layer - contract mechanically enforced; SQLite (WAL) with forward-only numbered - migrations and no ORM; a React/Vite SPA admin talking to a screen-shaped - REST BFF; scenario-bound end-to-end tests (one test per BDD scenario ID); - OHM concepts cited inline next to the rules they ground. -- **Invert** (the prototype's bootstrap was the wrong way round for a real - product): **no seeded tenant and no admission gate.** The prototype was born - with one hard-coded store and one invited owner; ecomm is born *empty*. - Identity is open sign-up via **email + one-time code** (passwordless; - corpus 14.01.0003–0004), the storefront is created *through the product* by - its merchant, and an empty database is a first-class, fully working state — - which is precisely what makes BUC-5's bootstrap story true by construction - rather than by tooling. -- **Defer** (YAGNI for four screens): the prototype's second API surface - (GraphQL) is not built in this MVP; the layering keeps the seam so it can be - added later as a projection over the same domain core. Google/Apple OAuth - and sign-in-by-emailed-link (corpus 14.01.0005–0007) are deferred the same - way — the email-canonical identity rule (14.01.0010) keeps them addable - without account migration. - -**Why this approach** over the alternatives: - -- *Do nothing / concierge* (hand-create merchants on request): fails BUC-5 - outright (every merchant is hand-seeded state) and validates nothing — the - prototype already validated the need; the open question is productionizing. -- *Re-architect on a heavier stack* (Postgres, separate services, SSR - framework): buys scale and rendering properties the MVP measurably does not - need, at the cost of slower iteration and a bigger bootstrap surface — - directly against the "launching anywhere is routine" outcome (§1.6). The - single-VM flotilla deployment standard (handbook §8) favors the lighter - stack; revisit at real scale (§6.7, §7.4). -- *Resume the prototype codebase*: it bakes in the seeded-tenant and - invite-gate assumptions at the foundation, and the rebuild exists precisely - to lay clean foundations. Its *patterns* are kept; its code is reference - only. - -**Solution-specific scope:** the landing page, sign-up/log-in (email + -one-time code), create-storefront (both entry points: post-sign-up and -returning-without-storefront), the empty admin shell, sign-out, and the -bring-up story for localhost/PPE/Prod including real email delivery in -deployed environments. - -**Solution-specific non-goals (this release):** GraphQL surface; OAuth -providers and magic-link completion; the onboarding questionnaire and POS -opt-in from the corpus first-run flow (14.01.0017–0024) — the merchant lands -directly on their admin; storefront rename/settings (14.01.0025 makes naming -optional at creation; *changing* it later is the Settings Feature's job); -account-lifecycle polish beyond what passwordless entry gives for free -(password reset does not exist because passwords do not exist; the one-time -code *is* email verification; account deletion is deferred and logged in §9). - ---- - -## 3. Product Personas - -| Product persona | In ecomm | Maps to business role(s) | -| --- | --- | --- | -| **Visitor** | An unauthenticated person on the entry surfaces: landing, sign-up/log-in. | Merchant (before they are known) | -| **Merchant** | An authenticated account holder; creates and owns the storefront; lands on its admin. The MVP's only authenticated user type. | Merchant | -| **Operator** | Brings up and deploys environments; interacts through flotilla and the bring-up runbook, not the web UI. | Platform operator; ecomm team | - -## 4. Product Use Cases - -Corpus grounding: scenario IDs cite the harvested Shopify first-run experience -([flows/first-run-experience.md](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify/flows/first-run-experience.md), -14.01.\*) and the zero-state dashboard (01.01.0008). Divergences are marked. - -**PUC-1 — Landing offers the two doors** *(realizes BUC-1, BUC-2; corpus 14.01.0001)* - -```gherkin -Scenario: PUC-1 — The landing page offers signing up or logging in - Given a Visitor on the ecomm landing page - Then they see what ecomm is, a primary action to get started, and a link to log in - And no trial, pricing, or fee is presented (corpus 14.01.0011) -``` - -**PUC-2 — Sign up with email + one-time code** *(realizes BUC-1; corpus 14.01.0002–0004)* - -```gherkin -Scenario: PUC-2 — A Visitor signs up - Given a Visitor who chose to get started - When they enter their email address and request a code - Then a one-time code is sent to that address - And the screen moves to code entry, telling them where the code went - When they enter the code within its validity window - Then they are signed in as a new Merchant - And they are taken directly into creating their storefront (PUC-4) -``` - -```gherkin -Scenario: PUC-2a — Wrong code - Given a Visitor on the code-entry screen - When they enter an incorrect code - Then the screen says the code didn't match and lets them retry or request a new one - And after repeated failures the code is invalidated and a fresh request is required -``` - -```gherkin -Scenario: PUC-2b — Expired code - When they enter a code past its validity window - Then the screen says the code expired and offers to send a fresh one -``` - -```gherkin -Scenario: PUC-2c — Resend is rate-limited - When they ask for another code immediately after one was sent - Then the screen asks them to wait briefly before resending -``` - -**PUC-3 — Log in as a returning Merchant** *(realizes BUC-2; corpus 14.01.0009, 14.01.0010)* - -```gherkin -Scenario: PUC-3 — A returning Merchant logs in - Given a Visitor whose email already belongs to a Merchant account - When they complete the same email + code flow (from either door) - Then they are signed in to that same account — the email is the canonical key - And no duplicate account is created (corpus 14.01.0010) -``` - -*(Sign-up and log-in are deliberately the same mechanism; the two doors differ -only in framing. A "sign up" with a known email is a log-in; a "log in" with an -unknown email creates the account. Honest copy on the code-entry screen states -which happened.)* - -**PUC-4 — Create the storefront after sign-up** *(realizes BUC-3; corpus 14.01.0013, 14.01.0015, 14.01.0016, 14.01.0025, 14.01.0026)* - -```gherkin -Scenario: PUC-4 — A new Merchant creates their storefront - Given a Merchant signed in with no storefront - Then they are on the create-storefront screen — there is nothing else to do yet - When they optionally enter a storefront name and confirm - Then the storefront is created — named as entered, or with a generated default name - And no payment method, plan, or commitment was requested (14.01.0015/0016) - And they land on the storefront's admin page (PUC-6) -``` - -**PUC-5 — Returning without a storefront → prompted to create** *(realizes BUC-3, BUC-4)* - -```gherkin -Scenario: PUC-5 — A Merchant who never finished creating one - Given a returning Merchant who has no storefront - When they log in - Then they arrive at the create-storefront screen (PUC-4), not an empty admin or an error -``` - -**PUC-6 — Returning with a storefront → straight to its admin** *(realizes BUC-4; corpus 14.01.0027)* - -```gherkin -Scenario: PUC-6 — A Merchant returns to their storefront - Given a returning Merchant who has a storefront - When they log in - Then they land directly on that storefront's admin page - And nothing further is mandatory (corpus 14.01.0027) -``` - -**PUC-7 — One storefront: no second-storefront affordance** *(realizes BUC-3a; **diverges** from corpus 14.01.0012/0014 — multi-store per account is deliberately not offered; see §9 D-2)* - -```gherkin -Scenario: PUC-7 — No "create another storefront" exists - Given a Merchant with a storefront - Then no surface offers creating another one - And directly invoking storefront creation anyway is refused with an honest - explanation that ecomm is one storefront per account today -``` - -**PUC-8 — The admin shell is honestly empty** *(realizes BUC-4; zero-state per corpus 01.01.0008)* - -```gherkin -Scenario: PUC-8 — Empty admin - Given a Merchant on their storefront's admin page - Then the page carries the storefront's name and the signed-in account's email - And states plainly that there is nothing to manage yet - And shows no fabricated metrics, fake modules, or teaser upsells -``` - -**PUC-9 — Sign out** *(product-only)* - -```gherkin -Scenario: PUC-9 — A Merchant signs out - Given a signed-in Merchant anywhere in the admin - When they sign out - Then their session ends and they are back on the landing page as a Visitor -``` - -**PUC-10 — A developer bootstraps localhost** *(realizes BUC-5; Operator-facing — the surface is a terminal, not a screen)* - -```gherkin -Scenario: PUC-10 — Clean checkout to first storefront, locally - Given a clean checkout of wiggleverse-ecomm and the documented prerequisites - When the developer runs the documented dev bring-up command - Then the app starts against an empty local store, applying schema migrations itself - And the developer completes sign-up → create storefront → admin in a browser - And the one-time code reaches them through the local dev channel (no real mail needed) -``` - -**PUC-11 — The Operator bootstraps a deployed environment (PPE, then Prod)** *(realizes BUC-5, BUC-5a)* - -```gherkin -Scenario: PUC-11 — Fresh deployed environment to first merchant - Given an environment provisioned and deployed through flotilla, with empty persistence - When the app starts, applying schema migrations itself - Then the first real merchant can complete sign-up → storefront → admin - through the public flows, with the code arriving by real email - And the rehearsal on PPE and the day-one Prod state are the same gesture (BUC-5a) -``` - -## 5. UX Layout - -Text is the source of truth; wireframes are generated from these descriptions -on demand and not committed. One SPA, four surfaces. Visual language: calm, -text-first, honest — no countdowns, no badges, no fake density. - -### 5.1 Screen: Landing (serves PUC-1) - -- **Purpose:** a Visitor learns what ecomm is and picks a door. -- **Layout (top → bottom):** - - **Header:** wordmark "ecomm" (left); "Log in" link (right). - - **Primary content:** one short value statement (what ecomm is, in OHM - voice — honest commerce, your storefront is yours); primary button - **"Create your storefront"**. - - **Footer:** minimal (project identity). -- **States:** happy only — static page. A signed-in Merchant hitting `/` is - redirected per entry routing (§6.5, PUC-6/PUC-5). -- **Notifications:** none. - -### 5.2 Screen: Sign in (serves PUC-2, PUC-3; two steps) - -- **Purpose:** the single email + one-time-code flow behind both doors. -- **Step 1 — email entry:** - - **Header:** wordmark; back-to-landing link. - - **Primary content:** heading framed by the door used ("Create your - storefront" / "Log in" — same form); email field (label "Email"; - autofocus); primary button **"Send code"**; one line of honest copy: - "We'll email you a one-time code. That's all we need." - - **States:** happy → step 2 · invalid email format: inline field error · - sending: button busy state · resend cooldown active: button disabled with - "you can resend in ~Ns" (PUC-2c) · delivery failure: banner "We couldn't - send the code — try again" (no fake success; §6.9). -- **Step 2 — code entry:** - - **Primary content:** "We sent a code to ⟨email⟩" (with a "wrong address?" - link back to step 1); code field (one-time-code input semantics); primary - button **"Continue"**; secondary "Resend code" (cooldown-aware). - - **States:** happy: session starts → entry routing (§6.5) · wrong code: - inline "That code didn't match" with attempts remaining (PUC-2a) · - expired: inline "That code expired" + resend offer (PUC-2b) · attempts - exhausted: code invalidated, prompt to request a fresh one · loading: - button busy. - - **Honest-copy rule (PUC-3):** after verification the screen states which - happened — "Welcome to ecomm" (new account) vs "Welcome back" (existing). -- **Notifications:** the one-time-code **email** (subject "Your ecomm code: - ⟨code⟩"; body: the code, its validity window, and "if you didn't request - this, ignore it"). In localhost/dev the code reaches the developer via the - dev channel instead (§6.5 PUC-10). - -### 5.3 Screen: Create storefront (serves PUC-4, PUC-5, PUC-7) - -- **Purpose:** a storefront-less Merchant establishes their one storefront. -- **Layout:** - - **Header:** wordmark; signed-in email (right) with a "Sign out" action - (PUC-9). - - **Primary content:** heading "Create your storefront"; name field (label - "Storefront name", explicitly optional — helper text "You can leave this - blank; we'll pick a placeholder name you can change later"); primary - button **"Create storefront"**. -- **States:** happy: → admin (PUC-6) · blank name: allowed — a default name is - generated (corpus 14.01.0026) · creating: button busy · already-owns - (defense in depth, PUC-7): banner "Your account already has its storefront" - + link to the admin · error: banner with retry. -- **Notifications:** none (no confirmation email — minimal channel use). - -### 5.4 Screen: Admin shell (serves PUC-8, PUC-9) - -- **Purpose:** the storefront's stable home; honestly empty in this release. -- **Layout:** - - **Header:** storefront name (left — the admin's anchor identity); - signed-in email + "Sign out" (right). - - **Primary content:** empty state — heading with the storefront's name, - one line: "There's nothing to manage yet. Catalog, orders, and settings - will appear here as ecomm grows." Nothing else: no zeroed metric tiles, - no locked-feature teasers (OHM: Agency & Anti-Manipulation — no - manufactured aspiration). -- **States:** happy/empty are the same state by design · loading: minimal - skeleton while `/me` resolves · session expired: redirect to sign-in. -- **Notifications:** none. - -## 6. Technical Design - -### 6.1 Invariants - -- **INV-1 — Empty is a working state.** The application boots against empty - persistence, applies its own schema migrations, and serves the full - sign-up → storefront → admin flow. No code path assumes a pre-existing row; - there is no seed step. *Enforced mechanically:* the bootstrap test (§6.8) - runs the whole flow from a fresh database; it is the first test of the - suite. -- **INV-2 — Email is the canonical account key.** One account per email - (case-insensitively normalized); any future auth method resolves to the - same account by email (corpus 14.01.0010). *Enforced:* unique index on the - normalized email column. -- **INV-3 — One-time codes are handled like secrets.** Stored only as hashes; - expire after 10 minutes; single-use; at most 5 verification attempts per - code; resend no more than once per 60 seconds per email. Codes never appear - in production logs or API responses. *Enforced:* schema (consumed/attempt - columns) + service-layer checks + tests. -- **INV-4 — One storefront per account is the MVP rule, not the schema.** - Ownership lives in a membership relation that admits many storefronts per - account and many members per storefront; the *service layer* refuses a - second storefront for the same account today (and the UX never offers it, - PUC-7). Lifting the rule later is deleting one check, not a migration. - *Enforced:* service-layer guard + test; no `UNIQUE(account_id)` anywhere in - the storefront path. -- **INV-5 — Every storefront-scoped row carries its storefront.** All future - tenant data references `storefront_id`; nothing tenant-scoped is global. - (Trivially satisfied by this MVP's two tenant tables; stated now because it - binds every later Feature.) *Enforced:* schema review + FK constraints. -- **INV-6 — One source of truth for rules.** Authentication, authorization, - and the one-storefront guard live in the domain layer exactly once; every - API surface (today REST; later GraphQL) delegates to them. *Enforced:* - layering contract (import-linter) + the API layer owning no business logic. -- **INV-7 — Migrations are forward-only and fail-stop.** Numbered `.sql` - files applied in order at startup, recorded in a migrations table; a failed - migration aborts startup (the deploy fails; the prior version keeps - serving). No down-migrations. -- **INV-8 — No deployment shape in framework code.** URLs, mail relay - coordinates, secrets: all arrive via environment/deployment configuration - (resolved from Secret Manager in deployed environments); none are baked - into the app (handbook §5.3). *Enforced:* config surface table (§6.6) + - review. -- **INV-9 — Honest failure.** When the platform cannot do what was asked - (code not sent, storefront not created), the user is told so — no fake - success, no silent drop (OHM: Transparency & Traceability). - -### 6.2 High-level architecture - -```mermaid -flowchart LR - subgraph Browser - SPA[Admin SPA
React + Vite] - end - subgraph "ecomm backend (FastAPI, one process)" - BFF[REST BFF
main.py] - subgraph domains - ACC[accounts
identity · OTC · sessions] - SF[storefronts
storefront · membership] - end - subgraph platform - DB[db
SQLite WAL + migrations] - MAIL[mailer
port: log / SMTP] - DEPS[deps
request wiring] - end - end - STORE[(SQLite file)] - RELAY[SMTP relay
deployed envs only] - - SPA -->|JSON /api/*| BFF - BFF --> ACC - BFF --> SF - ACC --> DB - SF --> DB - ACC --> MAIL - DB --> STORE - MAIL -.-> RELAY -``` - -Layering is the prototype's four-layer contract, mechanically enforced with -import-linter: `main` (entrypoint + REST BFF) → `domains` → `platform`; -imports flow only downward; domains are imported via their package surface -(`__all__`), never by reaching into modules. - -- **Admin SPA** — the four surfaces of §5; owns no rules. Renders what the - BFF returns; must never enforce a business rule the backend doesn't (the - UX-level one-storefront affordance is presentation; the rule is INV-4's - service guard). -- **REST BFF (`main.py`)** — screen-shaped JSON endpoints, one round-trip per - screen; translates HTTP ↔ domain calls; owns no business logic (INV-6). -- **`accounts` domain** — owns identity: account records, one-time-code - issue/verify (INV-2, INV-3), session establishment, the signed-in-user - gate. Must never know what a storefront is. -- **`storefronts` domain** — owns the storefront entity and the - account↔storefront membership (INV-4, INV-5), including the entry-routing - answer ("which storefront, if any, does this account have?"). Must never - mint identity. -- **`platform/db`** — SQLite WAL connection + forward-only migration runner - (INV-7); owns the schema lifecycle, no business rules. -- **`platform/mailer`** — a one-method port (`send(to, subject, body)`) with - two adapters: `LogMailer` (localhost/dev and tests — the message lands in - the app log / a test inbox) and `SmtpMailer` (PPE/Prod — relay coordinates - from deployment config, INV-8). Chosen by configuration at startup. -- **`platform/deps`** — FastAPI dependency wiring: per-request DB connection, - current-session resolution, configured mailer. - -Sessions are signed HTTP-only cookies (server secret from configuration; no -session table). MVP-honest: signing out clears the cookie; a leaked signing -secret is rotated by replacing the configured secret, which invalidates all -sessions at once. Revisit (server-side sessions) when staff/multi-device -management arrives. - -### 6.3 Data model & ownership - -| Entity | Owned by | Key fields | System of record | -| --- | --- | --- | --- | -| `account` | accounts | `id`, `email` (unique, normalized — INV-2), `created_at` | SQLite | -| `auth_code` | accounts | `id`, `email`, `code_hash`, `expires_at`, `attempts`, `consumed_at`, `created_at` (INV-3) | SQLite | -| `storefront` | storefronts | `id`, `name`, `created_at` | SQLite | -| `storefront_membership` | storefronts | `account_id` (FK), `storefront_id` (FK), `role` (MVP: always `'owner'`), `created_at`; PK `(account_id, storefront_id)` | SQLite | - -Notes: - -- **Data minimization (OHM):** the account stores the email and nothing else — - no name, no phone, no profile (corpus sign-up asks for nothing more; - prototype precedent). A display name arrives only when a Feature needs it. -- `auth_code` rows are keyed by *email*, not account, because the code is - issued before the account may exist (sign-up and log-in converge, PUC-3). - Consumed/expired rows are purged opportunistically on issue. -- `storefront_membership.role` is a single-value enum today; it is the seam - where the corpus's staff & permissions model (13.15.\*) attaches later - without reshaping ownership (INV-4 rationale). -- `storefront.name`: when the merchant leaves it blank, a generated default - (e.g. "⟨email local-part⟩'s storefront") is stored — the column is always - populated; "unnamed" is a naming choice, not a NULL (corpus 14.01.0026). - -### 6.4 Interfaces & contracts - -All JSON over `/api/*`; session via signed cookie. Errors share one shape: -`{"error": {"code": "", "message": ""}}`. - -| Endpoint | In | Out | Errors | -| --- | --- | --- | --- | -| `POST /api/auth/request-code` | `{email}` | `204` — code issued & dispatched. Response is identical whether the email is new or known (no account enumeration). | `400 invalid_email` · `429 resend_cooldown` (with `retry_after_s`) · `502 delivery_failed` (INV-9 — the relay refused; dev `LogMailer` cannot fail) | -| `POST /api/auth/verify` | `{email, code}` | `200 {account: {email}, storefront: {id, name} \| null, created: bool}` — session cookie set; `created` drives the honest welcome copy (PUC-3); `storefront` drives entry routing (§6.5). | `400 code_mismatch` (with `attempts_remaining`) · `400 code_expired` · `400 code_exhausted` | -| `GET /api/auth/me` | — | `200 {account: {email}, storefront: {id, name} \| null}` | `401 unauthenticated` | -| `POST /api/auth/logout` | — | `204` — cookie cleared | — (idempotent) | -| `POST /api/storefronts` | `{name?: string}` | `201 {id, name}` — membership row created with `role='owner'` | `401 unauthenticated` · `409 already_owns_storefront` (INV-4, PUC-7) | -| `GET /healthz` | — | `200 {status: "ok"}` — process up, DB reachable, migrations current | `503` otherwise (deploy gate, §6.9) | - -Contract stance: these are the stable seams the SPA and the tests bind to; -adding fields is free, renaming/removing is a spec change (this document, -§3.1-handbook). - -### 6.5 Per–Product-Use-Case design - -#### Entry routing (the shared spine: PUC-1, PUC-5, PUC-6) - -One client-side rule, fed by one server answer, decides where any arrival -lands. The server's answer is `GET /api/auth/me` (or the `verify` response, -which carries the same shape): - -| Session | Storefront | Lands on | -| --- | --- | --- | -| none | — | Landing (PUC-1) | -| valid | `null` | Create storefront (PUC-5) | -| valid | present | Admin shell (PUC-6) | - -The rule is exhaustive — no state lands nowhere (BUC-4's "never stranded"; -OHM: Duty of Care). The SPA router applies it on load and after `verify`. - -#### PUC-2 / PUC-3 — Sign up & log in (one flow; realizes BUC-1, BUC-2) - -```mermaid -sequenceDiagram - actor V as Visitor - participant SPA as Admin SPA - participant BFF as REST BFF - participant ACC as accounts - participant SF as storefronts - participant M as mailer (port) - participant DB as SQLite - - V->>SPA: enter email, "Send code" - SPA->>BFF: POST /api/auth/request-code {email} - BFF->>ACC: request_code(email) - ACC->>DB: upsert auth_code (hash, expiry; cooldown check) - ACC->>M: send(email, "Your ecomm code: …") - ACC-->>BFF: ok (uniform, new-or-known) - BFF-->>SPA: 204 → code-entry step - V->>SPA: enter code, "Continue" - SPA->>BFF: POST /api/auth/verify {email, code} - BFF->>ACC: verify(email, code) - ACC->>DB: check hash, expiry, attempts; consume (INV-3) - ACC->>DB: get-or-create account by normalized email (INV-2) - ACC-->>BFF: account, created? - BFF->>SF: storefront_for(account) — via domains, for the routing answer - BFF-->>SPA: 200 {account, storefront|null, created} + session cookie - SPA-->>V: honest welcome → entry routing -``` - -- **Implementation:** `request_code` is uniform for new vs known emails (no - enumeration, §6.6) and enforces the 60s cooldown (INV-3 → PUC-2c). - `verify` consumes the code transactionally — increment attempts on - mismatch (PUC-2a), refuse expired (PUC-2b), invalidate at 5 (INV-3) — and - only then gets-or-creates the account (INV-2). Account creation *is* email - verification: the address provably received the code. Honors INV-1 (works - on an empty DB: the first verify creates account #1), INV-6, INV-9. - -#### PUC-4 / PUC-7 — Create the storefront (realizes BUC-3, BUC-3a) - -```mermaid -sequenceDiagram - actor Mer as Merchant - participant SPA as Admin SPA - participant BFF as REST BFF - participant SF as storefronts - participant DB as SQLite - - Mer->>SPA: name (optional), "Create storefront" - SPA->>BFF: POST /api/storefronts {name?} - BFF->>SF: create_storefront(account, name?) - SF->>DB: any membership for account? (INV-4 guard) - alt already owns one - SF-->>BFF: refuse - BFF-->>SPA: 409 already_owns_storefront (PUC-7, honest copy) - else none yet - SF->>DB: insert storefront (name or generated default) + membership(owner) - SF-->>BFF: storefront - BFF-->>SPA: 201 {id, name} - SPA-->>Mer: → admin shell (PUC-6) - end -``` - -- **Implementation:** guard + insert run in one transaction (two concurrent - creates cannot both pass the guard). Default naming per §6.3. No payment, - plan, or extra field exists to ask for (corpus 14.01.0015/0016). Honors - INV-4, INV-5, INV-6. - -#### PUC-8 — Admin shell (realizes BUC-4) - -No new backend surface: the shell renders from `GET /api/auth/me` -(storefront name + account email) and is otherwise static honest-empty copy -(§5.4). Honors INV-9 — it claims nothing that doesn't exist. - -#### PUC-9 — Sign out - -`POST /api/auth/logout` clears the session cookie; SPA returns to Landing. -Idempotent; no server state to destroy (sessions are cookie-borne, §6.2). - -#### PUC-10 / PUC-11 — Bootstrap (realizes BUC-5, BUC-5a) - -```mermaid -sequenceDiagram - participant Op as Operator / Developer - participant App as ecomm process - participant DB as SQLite (empty file or absent) - actor Mer as First merchant - - Op->>App: start (dev script · flotilla deploy) - App->>DB: open/create; apply pending migrations in order (INV-7) - App-->>Op: /healthz 200 (migrations current) - Mer->>App: sign up → create storefront → admin (the ordinary PUC-2/4/6 flows) - Note over App,Mer: first rows created through the product alone (INV-1) -``` - -- **Implementation:** identical in all three environments; only configuration - differs (INV-8): **localhost** — `scripts/dev.sh` from a clean checkout - (venv + deps, backend on :8000, Vite on :5173 proxying `/api`); mailer is - `LogMailer`, so the one-time code appears in the backend log (the "local - dev channel" of PUC-10 — auth itself is not stubbed; the same issue/verify - path runs). **PPE/Prod** — provisioned and deployed through - flotilla/launch-app (operator gesture, handbook §8.5); mailer is - `SmtpMailer` with relay coordinates and secrets resolved from Secret - Manager via deployment config; migrations apply at startup under - flotilla's fail-stop deploy, gated by `/healthz`. The bring-up runbook - (per-environment: prerequisites, the one gesture, how to watch `/healthz`) - ships in-repo as `docs/BOOTSTRAP.md` — the documented gesture BUC-5 - demands. - -### 6.6 Non-functional requirements & cross-cutting concerns - -- **Security & privacy:** - - Authn: email + one-time code per INV-3; sessions in signed, HTTP-only, - `SameSite=Lax` cookies, `Secure` in deployed environments. - - Authz: MVP has one rule — you act only on your own storefront — enforced - in the domain layer (INV-6). - - No account enumeration: `request-code` answers uniformly for new and - known emails. - - Data classification: emails are personal data — the only personal data - held (§6.3); code hashes are short-lived secrets; both excluded from - logs in deployed environments. - - Secrets are references, never bytes (handbook §6.3): session secret and - SMTP credentials live in Secret Manager, named by deployment config - (INV-8). -- **Performance & scale:** MVP traffic is near-zero; the bar is honesty, not - throughput — interactive responses well under a second on the standard - single-VM deployment. SQLite/WAL with per-request connections is far above - this bar; revisit at real scale (§7.4 R-3). -- **Availability & resilience:** one VM, one process (standard flotilla - stack); deploys are fail-stop with `/healthz` gating; brief deploy-window - unavailability is accepted pre-v1. -- **Observability:** structured request logs (no emails/codes in deployed - logs); `/healthz` reporting migration currency; auth events (code issued / - verify ok / verify failed) logged with hashed identifiers — enough to see - the bootstrap rehearsal happen and debug delivery. -- **Accessibility:** the four screens are forms and text — semantic HTML, - labelled fields, keyboard-completable flows, visible focus; the code input - carries one-time-code semantics so password managers and OS autofill - cooperate. - -### 6.7 Key decisions & alternatives considered - -| Decision | Chosen | Alternatives considered | Why chosen | -| --- | --- | --- | --- | -| Overall shape | Carry forward the prototype's 4-layer modular monolith + React SPA | Heavier re-architecture (Postgres, services, SSR); resume prototype code; new stack | Proven by R01–R07 against this exact domain; smallest bootstrap surface (§1.6 outcome 3); rebuild wants clean *code*, not unproven *shape* (§2) | -| Datastore | SQLite (WAL), no ORM, forward-only `.sql` migrations | Postgres (managed or on-VM) | Single-VM flotilla standard; zero standing service to provision per environment — bootstrap stays one gesture; prototype precedent. Revisit at scale (R-3) | -| Tenancy | One shared DB; tenant rows carry `storefront_id` (INV-5); ownership via membership relation | DB-per-storefront; hard 1-1 FK on account | Membership keeps the many-per-account door open (Feature #1 constraint) and is the staff-model seam (13.15.\*); DB-per-tenant multiplies the bootstrap story for no MVP gain | -| One-storefront rule | Service-layer guard + no UX affordance (INV-4) | UX-only; schema `UNIQUE(account_id)` | UX-only leaves the API dishonest (data could contradict the promise); schema-level closes the door Feature #1 says to keep open. The guard is one deletable check | -| Auth mechanism | Email + one-time code, passwordless | Passwords (+ reset/verification machinery); OAuth (Google/Apple) first | Corpus's primary path (14.01.0003–0004); prototype-proven; collapses the account-lifecycle question — no passwords to reset, verification inherent. OAuth deferred, addable under INV-2 | -| Admission | Open sign-up, no gate | Prototype's pending/granted invite gate | ecomm is a product, not an internal tool; a gate would hand-curate exactly what BUC-5 says must be flow-reachable. Explicit §1.7 non-goal | -| Bootstrap | No seed; empty DB is a working state (INV-1) | Prototype's seeded store/owner; seed scripts per environment | Seeding *is* hand-placed data — it's what Feature #1's acceptance forbids; INV-1 makes the bootstrap story a property of the app, not of tooling | -| API surface | REST BFF only; GraphQL deferred | Prototype's dual REST + GraphQL from day one | Four screens don't justify a second surface; INV-6's one-source-of-truth layering keeps GraphQL addable as a projection later | -| Email delivery | `mailer` port: `LogMailer` (dev/tests) / `SmtpMailer` (deployed); relay is deployment config | Provider SDK baked in; building codes-only without real mail | Port keeps INV-8 (no deployment shape in code) and makes the provider an operator choice (§9 Q-1); real mail is required by Feature #1's "no stubbed auth" in PPE/Prod | -| Sessions | Signed cookie, no session table | Server-side session rows | No revocation/multi-device requirement yet; cookie sessions are one less table and zero queries; revisit with staff (§6.2 note) | -| Vocabulary | **Storefront** is ecomm's canonical noun (corpus "store" maps to it) | Adopt corpus "store" | The charter, Feature #1, and repo names all say storefront; glossary (§10) carries the mapping so corpus scenario IDs still read cleanly | - -### 6.8 Testing strategy - -The prototype's discipline, inherited: - -- **Scenario-bound end-to-end tests** drive the app through its HTTP surface - (FastAPI TestClient on a fresh temp DB). Where a corpus scenario covers the - behavior, the test name embeds its ID (`test_14_01_0003_email_code_sent`); - PUCs without a corpus ID bind to the PUC (`test_puc_05_...`). One test per - scenario/PUC, including every unhappy path in §4. -- **The bootstrap test is INV-1's enforcement:** from an empty database, one - test walks request-code → verify → create-storefront → `/me` → admin - answer, asserting no step needed seeded state. A second asserts - `migrate()` is idempotent (re-running applies nothing). -- **Invariant tests** for the sharp edges: code expiry/attempt - exhaustion/cooldown (INV-3), concurrent second-storefront refusal (INV-4), - enumeration uniformity (§6.6), `LogMailer` capture in tests. -- **Frontend:** typecheck + production build in CI; the entry-routing rule - (§6.5) unit-tested; component/E2E browser tests deferred until there is UI - beyond forms. -- **Gate:** `scripts/check.sh` = `lint-imports` (layer contract, INV-6) + - `pytest` + frontend typecheck/build — locally pre-merge and in CI. "Tested" - for a slice (§7.2) means its scenarios are green in this gate. -- **PPE tier:** the §7.2 SLICE-4 rehearsal *is* the deployed-tier test — the - product flows walked against PPE with real mail before Prod exists. - -### 6.9 Failure modes, rollback & flags - -- **Mail relay down / refuses** → `request-code` returns `502 - delivery_failed`; the user is told the code didn't go out (INV-9, §5.2) — - never a fake 204. Operator sees it in logs; codes are re-requestable, no - state is corrupted. -- **Migration fails at startup** → process refuses to start (INV-7); - flotilla's fail-stop deploy keeps the prior version serving; operator fixes - forward (no down-migrations — MVP migrations are additive). -- **DB file lost/corrupted** → restore from VM disk snapshot (the standard - flotilla VM's recovery story); accepted pre-v1 bar — an explicit backup - cadence is deferred and logged (§9 Q-2). -- **Session-secret leak** → rotate the secret in Secret Manager + redeploy; - all sessions invalidate at once (accepted blast radius at MVP scale, - §6.2). -- **Code-guessing attempts** → INV-3's attempt cap and cooldown bound the - attack; events are logged. -- **Rollback** = flotilla redeploy of the previous version; additive-only - MVP migrations make old-code-on-new-schema safe. -- **Feature flags / kill switch:** none — pre-v1, nothing to protect that a - redeploy doesn't cover; first flags arrive when there are users to shield. - -## 7. Delivery Plan - -### 7.1 Approach / strategy - -Walking skeleton first, then the two domains in dependency order, then the -deployed environments — riskiest-last is wrong here: the *deploy* story is the -novel risk (the prototype never deployed), so it gets its own slice with -everything else already green, and PPE rehearses Prod (BUC-5a) rather than -both being attempted at once. - -Execution convention (per the handbook): each slice is its own -planning-and-executing session — implementation plan written just-in-time at -session start → execute → verify → merge + version bump. The design pass is -this document, once; if a slice proves it wrong, amend the spec, then replan. -Slice tasks live in each slice's plan, not here. - -### 7.2 Slicing plan - -#### SLICE-1 — Walking skeleton → completes PUC-10 (localhost half of BUC-5) - -- **Depends on:** — -- **Ships:** repo scaffold (backend 4-layer skeleton + import-linter - contract, frontend Vite/React shell, `scripts/check.sh`, CI); `platform/db` - with the migration runner (INV-7) and migration `0001` (the §6.3 schema); - `/healthz`; `scripts/dev.sh`; first cut of `docs/BOOTSTRAP.md` (localhost - section). -- **Definition of done:** clean checkout → `scripts/dev.sh` → app up on an - empty, self-migrated DB; `/healthz` green; check gate green in CI; the - bootstrap test skeleton runs migrate-from-empty + idempotent re-migrate - (INV-1 partial — full flow lands with SLICE-2/3). - -#### SLICE-2 — Identity → completes PUC-1, PUC-2 (+a/b/c), PUC-3, PUC-9 - -- **Depends on:** SLICE-1 -- **Ships:** `accounts` domain (request-code / verify / sessions / me / - logout per §6.4–6.5), `platform/mailer` port with `LogMailer`, Landing + - Sign-in screens, entry routing with storefront hard-wired `null`. -- **Definition of done:** BUC-1/BUC-2 acceptance criteria met end to end on - localhost; scenario tests for 14.01.0001–0004, 0009–0011 and PUC-2a/b/c - green; INV-2/INV-3 invariant tests green; no enumeration (uniform 204) - asserted. - -#### SLICE-3 — Storefront → completes PUC-4, PUC-5, PUC-6, PUC-7, PUC-8 - -- **Depends on:** SLICE-2 -- **Ships:** `storefronts` domain (create + guard + membership per §6.5), - Create-storefront + Admin-shell screens, full entry routing, the complete - bootstrap test (INV-1 whole-flow). -- **Definition of done:** BUC-3/BUC-4 acceptance criteria met; scenario tests - for 14.01.0013/0015/0016/0025/0026/0027 and PUC-5/7/8 green; INV-4 - concurrent-create test green; localhost bootstrap (PUC-10) walkable start - to finish — BUC-5's dev third done. - -#### SLICE-4 — Deployed environments → completes PUC-11 (BUC-5, BUC-5a) - -- **Depends on:** SLICE-3; **operator gestures:** PPE + Prod provisioning via - launch-app/flotilla (handbook §8.5 — the session hands the operator the - commands and waits), SMTP relay choice + credentials into Secret Manager - (§9 Q-1). -- **Ships:** `SmtpMailer` + config wiring (INV-8), `deployment.toml`, - deployed-environment hardening from §6.6 (Secure cookies, log hygiene), - `docs/BOOTSTRAP.md` completed for PPE/Prod. -- **Definition of done:** bootstrap rehearsal executed on PPE — a real - sign-up → storefront → admin with a real emailed code — then the identical - gesture on Prod; both recorded in the runbook; Feature #1 acceptance fully - met; Feature #1 closed. - -### 7.3 Rollout / launch plan - -Pre-v1, single Prod: PPE rehearsal is the canary (SLICE-4); Prod day-one *is* -the bootstrap state; rollback is flotilla redeploy of the prior version -(§6.9). No staged exposure — there is no traffic to stage. - -### 7.4 Risks & mitigations - -| Risk | Likelihood / impact | Mitigation | -| --- | --- | --- | -| R-1: First-ever ecomm deploy — flotilla provisioning/deploy path unexercised for this app | M / H | Isolate in SLICE-4 with all product code already green; PPE before Prod; operator runs provisioning (handbook §8.5); wiggle-snip's deployment.toml as template | -| R-2: OTC email deliverability (spam-foldering, relay limits) kills real sign-ups | M / H | Relay is deployment config (swap without code, INV-8); rehearsal on PPE with real mailboxes before Prod; honest `delivery_failed` surfacing (INV-9) makes failures visible, not silent | -| R-3: SQLite write concurrency at real scale | L (MVP) / M | WAL + short transactions now; INV-5/INV-6 keep the storage seam clean for a Postgres move; revisit at the first scale-bearing Feature | -| R-4: Scope creep into admin features ("just one settings field…") | M / M | PUC-8's honestly-empty rule + §1.7 scope; anything beyond the shell is a new Feature | -| R-5: The 1-1 storefront rule calcifies into hidden assumptions | L / M | INV-4 names the single deletable guard; membership schema + tests assert the many-capable shape stays intact | - -## 8. Traceability matrix - -| Pain | Business UC | Product UC | Slice | Tests | -| --- | --- | --- | --- | --- | -| PP-1 | BUC-1, BUC-1a, BUC-2 | PUC-1, PUC-2 (+a/b/c), PUC-3, PUC-9 | SLICE-2 | `test_14_01_0001…0004`, `test_14_01_0009…0011`, `test_puc_02a/b/c_*`, `test_puc_09_*`, INV-2/INV-3 tests | -| PP-2 | BUC-3, BUC-3a, BUC-4 | PUC-4, PUC-5, PUC-6, PUC-7, PUC-8 | SLICE-3 | `test_14_01_0013/0015/0016/0025/0026/0027`, `test_puc_05/07/08_*`, INV-4 test | -| PP-3 | BUC-1…BUC-4 (the real spine) | all of the above | SLICE-1…3 | the whole gate (`scripts/check.sh`) green on real persistence | -| PP-4 | BUC-5, BUC-5a | PUC-10, PUC-11 | SLICE-1, SLICE-4 | bootstrap test (INV-1), migrate-idempotence test; PPE + Prod rehearsals recorded in `docs/BOOTSTRAP.md` | - -Audit: every pain is relieved by at least one slice; every BUC is realized by -at least one PUC; every PUC lands in exactly one slice; every slice carries -tests. PUC-9 is product-only (no BUC) by design; BUC-1a is realized inside -PUC-2a/b (failed proof ≠ admission). - -## 9. Open Questions & Decisions log - -**Open** - -| # | Question | Owner | Blocks | -| --- | --- | --- | --- | -| Q-1 | Which SMTP relay/provider serves PPE and Prod? (Deployment-shape choice — config + Secret Manager entry, not code; the app speaks SMTP either way.) | Operator (Ben) | SLICE-4 deploy config only | -| Q-2 | Backup cadence for the Prod SQLite file beyond VM disk snapshots (and when does it graduate from "accepted pre-v1 bar", §6.9)? | Operator (Ben) | nothing in this Feature; revisit before real merchant data accrues | -| Q-3 | Account deletion / data export (OHM: Exit & Portability) — deliberately deferred from the MVP's honest bar; which Feature picks it up? | ecomm team | nothing here; must be captured as a Feature before public launch | - -**Resolved** - -| # | Decision | Resolution | Date | -| --- | --- | --- | --- | -| D-1 | Architecture for the clean rebuild | Carry forward the prototype's proven shape (4-layer monolith, SQLite/WAL, React SPA, REST BFF), invert seed + admission gate, defer GraphQL/OAuth — §2, §6.7 | 2026-06-10 | -| D-2 | One vs many storefronts per account | UX + service-layer 1-1 (INV-4) over a many-capable membership schema; conscious divergence from corpus 14.01.0012/0014, per Feature #1 | 2026-06-10 | -| D-3 | Auth bar for the MVP | Passwordless email + OTC; no passwords ⇒ no reset flow; OTC ⇒ verification inherent; OAuth/magic-link deferred under the email-canonical rule (INV-2) | 2026-06-10 | -| D-4 | Bootstrap mechanism | No seed anywhere; empty persistence is a working state (INV-1); migrations self-apply at startup (INV-7) | 2026-06-10 | -| D-5 | Canonical noun | "Storefront" (charter + Feature #1), with corpus "store" mapped in §10 | 2026-06-10 | -| D-6 | Corpus first-run steps not adopted | Onboarding questionnaire / POS opt-in (14.01.0017–0024) and multi-store selection (14.01.0012/0014) are out; merchant lands straight on the admin | 2026-06-10 | - -## 10. Glossary & References - -- **Storefront** — ecomm's unit of "a merchant's business presence": the - thing a merchant owns, manages, and (later) sells through. Maps to the BDD - corpus's **store** (corpus scenario text saying "store" reads as - "storefront" here — D-5). -- **Merchant** — the business actor who owns a storefront; as a product - persona, the authenticated account holder (the corpus's "Store Owner"). -- **Admin** — the merchant-facing management surface of a storefront; this - release ships its honestly-empty shell. -- **One-time code (OTC)** — the short-lived emailed code that is ecomm's - passwordless proof of identity (INV-3). -- **Entry routing** — the exhaustive arrival rule of §6.5: no session → - landing; session without storefront → create; session with storefront → - admin. -- **Bootstrap** — bringing an environment from empty persistence to "first - merchant, first storefront" through the product flows alone (BUC-5); - documented per environment in `docs/BOOTSTRAP.md`. -- **PPE** — the pre-production environment; Prod's rehearsal stage (handbook - §8). -- **flotilla** — the Wiggleverse operator CLI that provisions and deploys - app environments (handbook §8); provisioning is an operator-run gesture - (§8.5). -- **OHM** — the concept corpus at that grounds - ecomm's mechanics (Agency & Anti-Manipulation, Privacy & Data - Minimization, Transparency & Traceability, Duty of Care, …). -- **References:** - - Anchoring Feature: - - BDD corpus: - — esp. `flows/first-run-experience.md` (14.01.\*), `analytics/dashboard.md` - (01.01.0008), `settings/general.md` (13.06.\*), `settings/users-and-permissions.md` (13.15.\*) - - Reference prototype: - (R01–R07; SPEC.md, `.importlinter`, `platform/`, `domains/`) - - Engineering handbook & Solution-Design standard: - (`README.md`, - `solution-design/GUIDE.md`) - - Capture session for Feature #1: ecomm session 0019 (2026-06-10)