wiggleverse-ecomm/specs/SD-0001-mvp-sign-up-and-single-storefront.md

# 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** | `draft` |
| **Version** | v0.1.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 |

---

## 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 door is designed to stay open (§1.7, #1 acceptance).
  - 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

<!-- §2 pending -->

---

## 3. Product Personas

<!-- §3 pending -->

## 4. Product Use Cases

<!-- §4 pending -->

## 5. UX Layout

<!-- §5 pending -->

## 6. Technical Design

### 6.1 Invariants

<!-- §6.1 pending -->

### 6.2 High-level architecture

<!-- §6.2 pending -->

### 6.3 Data model & ownership

<!-- §6.3 pending -->

### 6.4 Interfaces & contracts

<!-- §6.4 pending -->

### 6.5 Per–Product-Use-Case design

<!-- §6.5 pending -->

### 6.6 Non-functional requirements & cross-cutting concerns

<!-- §6.6 pending -->

### 6.7 Key decisions & alternatives considered

<!-- §6.7 pending -->

### 6.8 Testing strategy

<!-- §6.8 pending -->

### 6.9 Failure modes, rollback & flags

<!-- §6.9 pending -->

## 7. Delivery Plan

### 7.1 Approach / strategy

<!-- §7.1 pending -->

### 7.2 Slicing plan

<!-- §7.2 pending -->

### 7.3 Rollout / launch plan

<!-- §7.3 pending -->

### 7.4 Risks & mitigations

<!-- §7.4 pending -->

## 8. Traceability matrix

<!-- §8 pending -->

## 9. Open Questions & Decisions log

<!-- §9 pending -->

## 10. Glossary & References

<!-- §10 pending -->