wiggleverse/wiggleverse-ecomm-content
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

spec(SD-0002 §1): business context — products bulk CSV import/export (#13)

Browse Source 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ben Stull
2026-06-11 08:29:04 -07:00
parent 7df301f8b0
commit 2cb6ccc947
1 changed files with 277 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
specs/SD-0002-products-bulk-csv-import-export.md
+277
View File
@@ -0,0 +1,277 @@
# Solution Design: Products — bulk CSV import/export
| | |
| --- | --- |
| **Anchor** | [wiggleverse/wiggleverse-ecomm#13](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/13) (`type/feature`, `priority/P1`) — parent epic [#12](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/12) |
| **Author(s)** | Claude (session ecomm-0030), for Ben Stull |
| **Reviewers / approvers** | Ben Stull |
| **Status** | `draft` |
| **Version** | v0.1.0 |
| **Source artifacts** | BDD corpus: [prototype rfcs 11-05-\* (products import/export)](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/rfcs) · [research/shopify/products](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype-content/src/branch/main/research/shopify/products/products.md) · Prototype: [wiggleverse-ecomm-prototype](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm-prototype) · Reference: Shopify product CSV · Builds on: [SD-0001](./SD-0001-mvp-sign-up-and-single-storefront.md) · Supersedes: — |
**Change log**
| Date | Version | Change | By |
| --- | --- | --- | --- |
| 2026-06-11 | v0.1.0 | Initial draft — §1 Business Context (session ecomm-0030) | Claude + Ben |
---
## 1. Business Context
*The business lens — solution-agnostic throughout. No mechanism is proposed until §2.*
### 1.1 Executive Summary
A merchant's catalog already exists before they ever meet this platform — in
spreadsheets, in their current platform's export, in the working files they
price and re-price every season. The value at stake is letting that catalog
*become* their storefront without re-entering it, letting catalog-wide changes
(a season's prices, a supplier's new costs) land as one gesture instead of
hundreds, and guaranteeing the catalog can leave whole at any time — so
adopting the platform never means retyping a business in, and never means
locking a business up. The beneficiaries are merchants — most acutely those
migrating from another platform — and the platform itself: every downstream
capability of an ecomm (browsing, orders, checkout) presupposes a real catalog
existing, and today none can.
### 1.2 Background
ecomm is Wiggleverse's multi-tenant Shopify alternative. Its first Solution
Design ([SD-0001](./SD-0001-mvp-sign-up-and-single-storefront.md)) shipped
sign-up, identity, and single-storefront creation: a merchant can exist and
their storefront can exist — and that storefront is, by design, an honestly
empty shell ("There's nothing to manage yet").
The Products MVP epic ([#12](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/12))
is the next move: give the storefront a real product catalog. The epic makes a
deliberate boundary decision: the MVP ships **no per-item editing** — bulk
ingestion and extraction is the *only* way product data moves. Its sibling
Features display the catalog
([#14](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/14),
list + read-only detail) and extend it to bundled offerings
([#15](https://git.wiggleverse.org/wiggleverse/wiggleverse-ecomm/issues/15),
kits); **this** Feature is the mechanism they all feed from.
The backdrop that makes bulk-first the right boundary: real merchant catalogs
are not built one item at a time inside an admin tool. Merchants switching
platforms hold their entire catalog as an export of their current system —
hundreds of products, each with variations, images, and prices. Merchants who
stay maintain their catalogs batch-wise: a seasonal price list, a supplier's
updated cost sheet, a spreadsheet kept as the working source of truth. The
catalog's natural lifecycle is bulk in, bulk update, bulk out.
### 1.3 Business Actors / Roles
Real-world roles — they exist whether or not this platform does.
| Role | Responsible for (in the business) |
| --- | --- |
| **Merchant** | Owns a storefront's catalog: what is sold, at what price, shown how. Keeps it current as seasons, suppliers, and stock change. |
| **Migrating merchant** | A merchant switching platforms. Their catalog already lives, complete, in their current system and its export files; they decide whether switching is worth the cost. |
| **Platform builder** | Builds and validates the capabilities a catalog feeds (browsing, orders, demos). Needs realistic catalogs to exist before those capabilities can be exercised. |
### 1.4 Problem Statement
A storefront can exist but cannot hold anything sellable: there is no way to
get product data into the platform at all, and the MVP deliberately offers no
per-item editing to fall back on. For the merchant whose catalog already
exists elsewhere — the common case — hand re-entry of hundreds of products,
each with variations, imagery, and prices, is a switching cost that simply
ends the conversation. The gap recurs after adoption: catalog maintenance is
batch-shaped (whole-catalog price changes, supplier updates), and one-at-a-time
upkeep mismatches how merchants actually work their data. And data that goes
in must come out: a catalog that cannot be extracted whole makes the platform
a trap, which careful merchants correctly treat as a reason not to enter.
### 1.5 Pain Points
| # | Pain | Who feels it | Cost / frequency today |
| --- | --- | --- | --- |
| PP-1 | A created storefront is a dead end — nothing to sell, nothing to manage, nothing to show | Merchant | Total: blocks any real use of the platform; felt by every merchant immediately after sign-up |
| PP-2 | An existing catalog would have to be re-keyed item by item to move over | Migrating merchant | Hundreds of products × dozens of fields each — a prohibitive switching cost; prospective merchants don't switch |
| PP-3 | Catalog-wide changes (season prices, supplier costs) have no whole-catalog gesture | Merchant | Recurring — every season, supplier change, or repricing event; effort scales with catalog size |
| PP-4 | No realistic catalog can be stood up to build, demo, or validate against | Platform builder | Continuous — every product-dependent capability (#14, #15, future orders) is blocked or faked |
| PP-5 | Whatever goes in cannot be gotten back out — the catalog would be trapped | Merchant | Felt at the adoption decision (a reason to say no) and at every backup/audit/leave moment after |
### 1.6 Targeted Business Outcomes
| # | Outcome | Success metric | Baseline → Target | Guardrail (must not regress) | How / when measured |
| --- | --- | --- | --- | --- | --- |
| BO-1 | Merchants with existing catalogs adopt — populating a storefront is hours, not weeks | # storefronts holding a real catalog; effort to first full catalog | 0 storefronts can hold a catalog → a several-hundred-product catalog lands in under an hour of merchant effort | Sign-up → storefront flow (SD-0001) stays intact | Platform records (operationalized §8.1); reviewed monthly |
| BO-2 | Catalog upkeep happens *in* the platform — merchants refresh in bulk rather than letting data go stale or leaving | # storefronts performing repeat bulk updates | No upkeep possible → catalog-holding storefronts update in bulk as their prices/data change | Existing catalog data never corrupted by an update | Platform records; reviewed monthly |
| BO-3 | "My data would be trapped" is a non-objection — the catalog is extractable whole, always | Full-catalog extraction available and exercised | No extraction exists → every storefront's complete catalog can be taken out on demand, at any time | Extraction completeness: nothing the merchant supplied is unrecoverable | Platform records; reviewed quarterly |
| BO-4 | Product-dependent work is unblocked — sibling and downstream capabilities build against real catalogs | #14 / #15 / future order work proceeding against realistic data | Nothing to build against → realistic catalogs standable in minutes | — | Delivery record of #14/#15; per Feature |
### 1.7 Scope (business)
- **In scope:** populating a storefront's catalog in bulk from records the
merchant already holds; updating the catalog in bulk; extracting the
complete catalog at any time. "Catalog" here means products in full
commercial reality: variations (size/color and the like), imagery,
organization (vendor, type, tags, category), pricing/cost, stock levels,
and publication state.
- **Out of scope:** per-item create/edit (a later epic — the MVP's deliberate
boundary); removing products in bulk (nothing is deleted by this mechanism —
see §2); automated or scheduled synchronization with other platforms;
movement of non-catalog data (customers, orders — other epics); the meaning
and behavior of bundled offerings (kits — Feature #15, which rides this
mechanism but defines its own semantics).
- **Non-goals:** real-time integration with other commerce systems (the
supplied file is the boundary, deliberately); making the MVP a catalog
*editing* tool of any kind.
### 1.8 Assumptions · Constraints · Dependencies
- **Assumptions:** merchants hold, or can readily produce, their catalog as a
structured file (a spreadsheet, their current platform's export). *Risk if
wrong:* a merchant with no digital catalog at all has no entry path in this
MVP. Catalogs at MVP scale run to a few thousand items. *Risk if wrong:*
larger catalogs need heavier machinery (a named seam, §2).
- **Constraints:** bulk-only is Epic #12's deliberate MVP boundary — this
design must not quietly grow per-item editing. One storefront per account
(SD-0001 INV-4) — a merchant's catalog context is unambiguous.
- **Dependencies:** SD-0001's shipped surfaces (identity, storefront, admin
shell) — live as of v0.4.0. Sibling #14 displays what this ingests; sibling
#15 extends what the records can express — both sequence after this
mechanism exists.
### 1.9 Business Use Cases
**BUC-1 — As a migrating merchant, I can bring my existing catalog into my storefront in one bulk gesture, so that switching platforms doesn't mean re-keying my business.**
```gherkin
Scenario: BUC-1 — An existing catalog comes over whole
Given a merchant whose catalog of several hundred products lives in an
export from their current platform
When they supply that catalog to their storefront in one gesture
Then the storefront holds the full catalog — every product with its
variations, imagery, organization, and prices
And nothing had to be re-entered by hand
```
- **BUC-1 acceptance criteria:** the catalog the storefront holds matches the
records the merchant supplied, completely; the merchant's effort is one
supply-and-review gesture, not per-product work.
**BUC-1a — unhappy path: unusable records are reported, not silently dropped.**
```gherkin
Scenario: BUC-1a — Unusable records come back with actionable feedback
Given a merchant supplies catalog records of which some are incomplete,
contradictory, or unreadable
When the storefront cannot accept some of the records
Then the merchant is told exactly which records failed and why, in terms
they can act on
And they can correct and re-supply the problem records
And nothing is silently dropped, guessed at, or invented
```
- **BUC-1a acceptance criteria:** every rejected record is identified with an
actionable reason; accepted vs. rejected is fully accounted for — the
merchant is never left wondering what made it in.
**BUC-2 — As a merchant, I can see exactly what a bulk change will do to my catalog before it happens, so that I never damage my own data by accident.**
```gherkin
Scenario: BUC-2 — A bulk change is reviewed before it takes effect
Given a merchant about to apply a bulk change to a catalog their business
depends on
When they supply the new records
Then they see what will be added, what will change (and to what), and what
is in error — before anything takes effect
And the change happens only when they say so
```
- **BUC-2 acceptance criteria:** the preview is complete and faithful (what it
shows is exactly what applying does); declining costs nothing; nothing
changes without the merchant's explicit go-ahead. *(OHM: consent & agency —
the merchant authorizes the change knowing what it is.)*
**BUC-3 — As a merchant, I can update my whole catalog at once, so that batch-shaped changes (seasonal prices, supplier costs) cost one gesture instead of hundreds.**
```gherkin
Scenario: BUC-3 — A catalog-wide change lands as one gesture
Given a storefront holding a catalog, and a season's repricing touching
most of it
When the merchant supplies the updated records
Then the affected products are updated to the new values
And the unaffected products are untouched
And no duplicates are created
```
- **BUC-3 acceptance criteria:** updates land on the products they target;
re-supplying unchanged records changes nothing (supplying the same catalog
twice never doubles it); the merchant's effort does not scale with catalog
size.
**BUC-4 — As a merchant, I can take my complete catalog out at any time, so that my business data is never trapped in the platform.**
```gherkin
Scenario: BUC-4 — The catalog leaves whole, on demand
Given a storefront holding a catalog the merchant built up over time
When the merchant asks for their catalog
Then they receive the complete catalog — every product, variation, image,
and price — in a form they can use elsewhere
And what they receive could rebuild the same catalog faithfully
```
- **BUC-4 acceptance criteria:** extraction is always available, complete
(nothing the merchant supplied is unrecoverable), and round-trips — what
comes out can go back in and reproduce the same catalog. *(OHM: agency —
leaving is always possible; the platform earns retention, never extorts
it.)*
---
## 2. Solution Proposal
*(not yet authored — next in the section-at-a-time loop)*
## 3. Product Personas
*(not yet authored)*
## 4. Product Use Cases
*(not yet authored)*
## 5. UX Layout
*(not yet authored)*
## 6. Technical Design
*(not yet authored)*
## 7. Delivery Plan
*(not yet authored)*
## 8. Success Metrics & Measurement
*(not yet authored)*
## 9. Telemetry, Observability & Monitoring
*(not yet authored)*
## 10. Operations
*(not yet authored)*
## 11. Documentation plan
*(not yet authored)*
## 12. Traceability matrix
*(not yet authored)*
## 13. Open Questions & Decisions log
*(not yet authored)*
## 14. Glossary & References
*(not yet authored)*