spec(§2): solution proposal — carry forward prototype shape, invert seed/gate, defer GraphQL+OAuth

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-10 07:03:57 -07:00
parent a68f59ac85
commit 7147e740a1
1 changed files with 55 additions and 1 deletions
@@ -237,7 +237,61 @@ Scenario: BUC-5a — Bring-up is rehearsable

 ## 2. Solution Proposal

-<!-- §2 pending -->
+**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).

 ---