v0 Scope Memo

Status

Authored: 2026-05-13. Last updated: 2026-05-18 — added design quality bar as a first-class v0 principle (UX is not deferred to v1 polish); removed retailer account management from admin UI scope (invite/disable handled via auth provider dashboard at v0, dedicated retailer invite UI deferred post-v0); anchored the medium supplier slot to a print music distributor archetype (was Sennheiser-like) to cover the Print Music v0-priority facet category and to apply Excel-with-human-formatting ingest pressure; anchored the degraded supplier slot to a drum-and-percussion wholesaler archetype with mixed-exclusivity portfolio (covers the Drums v0-priority facet category, applies emailed-attachment + schema-drift ingest pressure, and introduces deliberate accessory-tier overlap with other v0 suppliers so canonical identity resolution under cross-supplier collision is actually exercised at v0). The drum archetype commits v0 to a missing-column warning at ingest (if a saved mapping references a column absent from the incoming file, the ingest blocks and flags the operator — not a full schema-diff engine) and to a per-supplier missing-product handling setting in the mapping config; v0 ships two modes (ignore-missing-rows, snapshot-diff). Operator-confirm-per-push and grace-period are both deferred post-v0; suppliers like C with mixed snapshot/delta pushes and no source-side status signal default to snapshot-diff with known misclassification of products absent from delta pushes — v0's resolution is to request a status column from the supplier rather than build per-push operator gating. Previous 2026-05-17 update moved output filtering, retailer browse UI, and light retailer-tenancy into scope and removed the corresponding items from Scope OUT.
Stage: Pre-build. Strategic scope locked here; implementation specifics belong in the platform repo.
v0 is not an MVP. It is the first vertical slice of the platform, built to prove the design and to be demonstrable to industry contacts. Pre-commercial. No paying customers, no commercial commitments.

Why v0 (not MVP, not PoC)

MVP implies smallest-viable-for-sale. There is no paying customer yet, no priced offer, no commercial model — "MVP" framing would invite premature decisions (billing, multi-tenancy, support tooling, auth flows) for hypothetical customers.
PoC undersells what's being built — most of the design is well-enough understood that a single-narrow-feature proof isn't what's needed.
v0 is the right label: a real first slice of the actual platform, scope-disciplined, single-tenant, demonstrable, learn-and-iterate.

Load-bearing thesis v0 proves

The layered canonical + transformation model works. Concretely:

Supplier data from deliberately-varied sources ingests into a single canonical record per product.
The canonical record carries standardised categories + standardised facets/specs + clean primary fields.
From that one canonical record, two retailer-shaped outputs are produced via configurable transformations, without modifying the canonical layer.
Adding a third output shape is a transformation config, not a canonical-record change.

If steps 3 and 4 are clean, the platform thesis holds. If transformations keep forcing changes back into the canonical layer, the thesis is in trouble and v0 has surfaced it cheaply.

Why new-product onboarding anchors v0: operator evidence identifies new-product creation as both the most painful retailer workflow and the one that touches the most systems (POS, ecom, ERP, sometimes accounting). The layered model collapses that workflow into a single supplier → canonical → retailer-shaped-output flow, which is the most direct value v0 can demonstrate.

Scope IN

Supplier ingestion (2–3 distributors, deliberately varied)

Pick three distributors that span the data-quality range:

One rich-data distributor — clean fields, images, multiple specs (Fender-like profile). See supplier-a-profile.md.
One medium distributor — bibliographic-shaped catalogue, Excel-with-human-formatting ingest, multi-brand workbooks with per-file header drift, no MPN (supplier-SKU-fallback identity). Print music distributor archetype, covering the Print Music v0-priority facet category. See supplier-b-profile.md. Choosing this archetype commits v0 to first-class Excel ingest.
One degraded distributor — drum-and-percussion wholesaler with mixed-exclusivity portfolio (AU-exclusive on a few major drum / cymbal / electronic-percussion brands; non-exclusive on stick / head / small-percussion accessory brands also carried by other AU distributors). Emailed-attachment ingest with per-push schema drift, no source-side lifecycle column (discontinued rows vanish from next push), and deliberate accessory-tier overlap with other v0 suppliers. Covers the Drums v0-priority facet category. See supplier-c-profile.md. Choosing this archetype commits v0 to a missing-column warning in the mapping editor (operator awareness when a saved mapping's column is missing from a new file — not full schema-drift detection) and to per-supplier missing-product handling as a mapping-config setting with two v0 modes (see Per-supplier mapping config: v0 capabilities below). It is also the only v0 supplier exercising cross-supplier canonical identity resolution under collision — A and B are both AU-exclusive across their portfolios.

Selection criteria: diverse data shapes, not "the most important three." The goal is to exercise the normalisation layer against varied inputs.

Ingestion path: catalogue-file upload through a saved per-supplier mapping config. No supplier portal, no supplier-side push API at v0.

Per-supplier mapping config: v0 capabilities

The per-supplier mapping config is the load-bearing operator-facing surface for absorbing supplier variability. The three v0 suppliers together force these capabilities into scope:

Column-level mapping — field-to-field assignment, hardcoded values, derived/computed values, very simple if/then conditions (single condition per rule; no nested branching, no expression language at v0). (General mapping-editor scope, not supplier-specific.)
Multiple file variants per supplier. A single supplier may emit several file shapes (one per brand workbook, one per format band, etc.) with header drift between them. Each file variant carries its own mapping config under the parent supplier; the editor must support adding, editing, and removing variants under one supplier rather than forcing each variant to be its own supplier. Forced by Supplier B.
Missing-column warning at ingest. If a saved mapping references a column that's absent from the incoming file, the ingest blocks and flags it for the operator. Not a full schema-diff engine — no rename detection, no automated drift remediation, no per-column reconciliation UI. v0 expects operator awareness when a supplier changes their file shape; the operator hand-edits the saved mapping to absorb the change. Real schema-drift detection is deferred post-v0. Forced by Supplier C.
Missing-product handling. Per-supplier (or per-file-variant) setting that decides what happens to a previously-seen product that is absent from the current push. v0 ships two modes:
- Ignore missing rows. Rows persist as active until a source-column status flips them. Suits suppliers with a clean status column (Supplier A; Supplier B's status-column brands).
- Snapshot-diff. Every push treated as a full snapshot; any previously-seen row absent from the current push becomes inactive. Suits suppliers whose pushes are reliably full snapshots and whose OOP signal is row removal (Supplier B's row-deletion brands; also Supplier C's default).
- Operator-confirm-per-push (manual snapshot/delta gating at ingest time) and grace-period (last-seen-N-pushes-ago → inactive) are both deferred post-v0. Suppliers like C with mixed snapshot/delta pushes and no source-side status signal default to snapshot-diff with known misclassification of products absent from delta pushes; the v0 resolution is to request a status column from the supplier rather than build per-push operator gating. v0 treats this as a supplier data-quality issue, not a platform UX problem.

Forced by Supplier C; reused by A and B at the relevant granularity. Resolves the deletion-detection question via per-supplier mode choice. The snapshot-vs-delta interpretation question is intentionally not solved by v0 platform UX — suppliers that emit mixed pushes without a status column get snapshot-diff with known misclassification, and the v0 response is to escalate that to the supplier as a data-quality issue.

Canonical layer

Primary fields: SKU, MPN, GTIN/barcode, name, brand, supplier reference, RRP, cost, dimensions, weight, descriptions, images, lifecycle status (active / inactive), marketing highlights. Cost is a single canonical field — population varies by supplier (some files carry it directly; others derive it per-supplier in the ingestion mapping or leave it null). Image fields are URL pass-through to the supplier-provided CDN; the platform does not fetch, hash, or host image bytes at v0.
Categories: a full starter taxonomy derived from Sweetwater's structure, loaded as the canonical category set. Data ingestion in v0 flows through a smaller priority subset (see Facets/specs); remaining categories are present in the taxonomy and available for mapping but carry minimal data. The mapping editor exercises the full target taxonomy without requiring full data coverage.
Facets/specs: four priority categories carry curated facets in v0 — Electric Guitars, Pedals & Effects, Print Music, Drums — chosen for facet-shape diversity (classic gear specs / control + signal specs / publisher + composer + format / shell + dimensional). Prioritised facets per category, not exhaustive coverage. Standardised values per facet, with at least one example of multi-display-form values ("HH" / "Dual Humbucker") to prove that pattern works. The four-category choice is a v0 test case for the layered model's discriminating power, not a hard scope boundary — facet coverage in other categories is post-v0 work.
Identity resolution: MPN-anchored where present; supplier-SKU-fallback where MPN is missing.

Transformation layer

A retailer-configurable mapping editor (admin-only at v0).
Two pre-built retailer profile mappings:
GMI profile — Shopify-shape output.
CMS profile (see capital-music-sound-profile.md) — Cin7-shape CSV + Shopify-shape CSV.
Mapping editor surfaces: field-to-field mapping, hardcoded values, derived/computed values, very simple if/then conditions (single condition per rule; no nested branching, no expression language at v0).
Output schema is part of the transformation config. Each target platform (Cin7, Shopify, and future targets) has its own column set, column order, required fields, batch-size guidance, and format conventions (dimension units, weight units, currency, date formats). The mapping editor must absorb per-target output schemas as configuration, not hand-coded code paths per target. Cin7's inventory list import (~95 columns, three required) is the v0 stress case — see capital-music-sound-profile.md for the design implications it surfaces, in particular that required output fields can be retailer-overlay constants rather than supplier-sourced data.
Variant grouping policy is a transformation-time choice (variant-grouped output vs SKU-per-colour), proving the canonical record carries enough information for both views. Suppliers can opt in to expose grouping hints (model identifier + variant axes); the canonical layer carries these as available options that retailer transformations use or ignore.

Output surface

Filtered CSV exports per retailer profile. Exports are filter-driven by default — supplier, brand, canonical category, and lifecycle status. Whole-catalogue exports are an edge case, not the default; retailers will typically export batches. Downloadable from both the admin UI and the retailer UI.
Browse-capable read API. Read endpoints per resource (products, families) supporting pagination, filtering, and keyword search across canonical fields. The same API serves the admin UI, the retailer UI, and external API consumers (subject to access posture below).
API access posture. Admin/dev key works for internal admin usage and dev exploration. Retailer-scoped access (for the retailer UI and any retailer-driven external integration) is issued via the platform's auth provider. Public API access controls beyond this — rate limits, per-consumer keys, tiered access — remain out of scope at v0.

Admin UI

Catalogue upload + mapping editor (per supplier).
Canonical record browse/search.
Transformation/mapping editor (per retailer profile).
Export download (with the same filters available in the retailer UI).
Basic data quality view (missing-field reports for the v0 facet set).

Retailer account management (invite/disable) is handled via the auth provider's dashboard (e.g., Clerk) at v0, not built into the admin UI. A first-class retailer invite/management UI is post-v0.

Retailer UI

A retailer-facing surface inside the platform, alongside the admin UI. Scoped tightly at v0; deliberately not a full self-serve product yet.

Browse the canonical catalogue with filters (supplier, brand, canonical category, lifecycle status). Filter-driven, not facet-driven — facet-driven discovery remains a v1 concern.
Save filter sets per retailer for repeat use.
Trigger and download exports scoped by the active filter, output-shaped by the retailer's transformation profile.
Light retailer separation via the platform's auth provider (e.g., Clerk). The canonical catalogue itself is read-shared across retailers; what is per-retailer is saved filter sets, export history, and which transformation profile is "theirs." Retailer accounts are invite-only at v0 (admin issues invites); retailer self-signup is post-v0.
Out of scope for the retailer UI at v0: editing canonical data, editing transformation mappings (admin-only), retailer-overlay data management, billing or plan UI, in-app search beyond filter-driven browse.

Scope OUT

Explicit non-goals for v0:

Full multi-tenancy. Single canonical-data environment shared across all retailer accounts. Retailer accounts exist for light separation of saved state (filters, exports, owned transformation profile) but the canonical data layer is shared, not per-tenant.
Retailer self-serve signup. Retailer accounts are invite-only at v0. Light auth (login, session) is in scope via the platform's auth provider; signup, plan selection, billing, and account-management UX are not.
Supplier portal / supplier-side data entry.
Comprehensive integration support (e.g. Shopify API). CSV-only output for now.
Platform-hosted image storage. v0 passes through supplier-provided image URLs; image hosting (including content-hash-pinned storage) is post-v0.
Per-retailer cost overlay. Cost in the canonical layer is a single field shared across retailers at v0. Retailer-specific cost — trade-discount terms applied per retailer, per category, per brand — is real-world reality but is out of v0 scope. The transformation layer will absorb per-retailer cost as a post-v0 evolution.
Retailer-overlay data. v0 is supplier-data-out only. It does not ingest data set per-retailer in the retailer's existing systems — trade / sell prices, retailer-specific SKUs or titles, store-level inventory, retailer-specific tags or metafields, variant-packaging choices. Pulling this data is sync/diff territory, out of v0 scope. v0 exports surface supplier-provided fields (e.g. RRP only for pricing); retailers populate their own overlay fields in Shopify after import. Retailer-overlay management — retailers using the platform to manage their own product data alongside normalised supplier data — is an intentional post-v0 product direction, treated as a separate capability rather than a v0 extension.
Billing, pricing, commercial terms, subscriptions.
Comprehensive distributor coverage. Three deliberately-varied distributors is the target.
Production-grade reliability / SLA / uptime targets.
Support tooling, ops monitoring, alerting beyond local dev needs.
Public web presence, marketing site, SEO, indexed pages.
Mobile clients.
Search / facet-driven discovery UI. The canonical layer carries the facets; consumer-facing search is a v1 concern.
AI-assisted classification at scale. Manual curation at v0; AI is a v1 lever.
Reconciliation / two-way sync with retailer downstream systems. v0 is one-way: supplier → canonical → output.
Public API access controls, rate limits, API keys for external consumers.

Target consumer profiles

AU retail systems landscape (context for profile choice)

Typical stack components in AU music retail:

POS: MusiPOS, Shopify POS, Pronto POS, Lightspeed POS.
Ecommerce: Shopify (majority), Magento, WooCommerce, Neto.
ERP / accounting: Xero, MYOB, Cin7 Core/Omni, Unleashed.
Canonical-data location varies: POS, ERP, or Shopify depending on retailer maturity and channel mix. Loose connections between systems are typical.

The profiles below are drawn from this landscape; they are design forcing functions, not exhaustive coverage.

Profiles

v0 designs against three retailer profiles, not as paying customers but as design forcing functions:

GMI (real) — small, D2C, Shopify-centric, no Cin7. Boutique imports.
Hypothetical "Cin7-canonical mainstream retailer" (Capital Music & Sound / CMS) — Cin7 Core + Shopify Web + Lightspeed POS, single store + warehouse, schools-channel exposure, grouped multi-variant packaging. See capital-music-sound-profile.md.
Hypothetical "Shopify-native mainstream retailer" (Joe Bloggs Music / JBM) — Shopify POS + Shopify Web, multi-store + warehouse, broad mainstream AU catalogue. See joe-bloggs-music-profile.md.

Coverage matrix. The three profiles between them exercise the load-bearing design axes v0 needs to prove against. Each axis has at least one profile on each side.

Axis	GMI	CMS	JBM
Canonical hub	Shopify	Cin7 Core	Shopify
POS	none (D2C only)	Lightspeed (non-Shopify)	Shopify POS
Variant packaging	atomic (implicit)	grouped multi-variant	atomic 1:1
Output shape required	Shopify-shape	Cin7-shape + Shopify-shape	Shopify-shape
Catalogue scale	small (boutique)	mid (~11.5k SKUs)	large (~14.5k SKUs)
Catalogue character	boutique imports	schools / orchestral-leaning	broad mainstream AU
Store footprint	online-only	single store + warehouse	3 retail + warehouse
Real or fictional	real (design partner)	fictional	fictional

GMI's variant-packaging mode isn't explicitly captured in ../discovery/customer-zero-profile.md — assumed atomic given the boutique-import catalogue shape; worth confirming with Greg if it becomes load-bearing post-v0.

If the layered model produces sensible output for all three without canonical-layer bleed, the thesis is supported.

MusiPOS deferral. Earlier scoping included a "MusiPOS retailer" profile. Removed because migrating off MusiPOS is a full POS swap, not a PIM swap — even strong v0 value alone isn't enough to move an incumbent. MusiPOS retailers re-enter consideration post-v0, once the platform's value can credibly justify a POS migration carrot.

Data strategy

Synthetic data for the rich + medium distributor profiles — built from public industry knowledge.
Public supplier files where accessible (some distributors publish to dealer portals; permissible scraping).
GMI-permitted data for the boutique-import case (per the existing research/inputs/ permission).
No data drawn from systems Tyler accesses through other employment.

Tenancy and architecture posture

Single-tenant. All canonical data is one tenant's data; admin owns it.
Personal hardware. Built on Tyler's personal infrastructure; deploy decisions belong in the platform repo.
Stack choice. Decided in the platform repo. v0 scope doesn't constrain the stack except: must support a queryable read API and a configurable transformation layer.
Multi-tenancy is a v1 concern. When a second real consumer needs isolation, that's the trigger.

Design quality bar

UX is a first-class v0 priority, not a v1 polish concern. A platform competing for retailer attention needs to feel modern, considered, and credibly built from day one. v0 enforces design quality from the first commit — visual quality and interaction polish are not deferred to "after it works."

What this means in scope:

Considered visual design across every v0 surface — typography, spacing, hierarchy, restraint. No engineer-default UI.
Polished interaction states — loading, empty, error, success. Not skipped because v0 is pre-commercial.
A shared design system across admin and retailer surfaces from the first commit — cheaper to enforce now than retrofit.
The mapping editor is the highest-stakes interaction surface. The transformation layer is v0's load-bearing differentiator and its UI carries the value story; "passable" is not acceptable here.
The retailer UI is the surface most likely to be shown to industry contacts. It must feel like a product, not an admin tool.

What this explicitly does not mean:

Custom design from scratch. A well-chosen UI library / design system is the right starting point.
Visual maximalism or animation flourish. "Great" means refined and credible, not flashy.
Expanding feature scope to "make it more polished." The quality bar applies to what's already in scope, not as a justification for adding more.
Bespoke design for every screen. Consistency across the system is the higher virtue than uniqueness per screen.

This memo's job is to assert that the quality bar exists and to convey the kind of bar intended (Linear / Vercel / Stripe-class — refined, considered, restrained). Picking the specific visual reference is a platform repo decision, paired with the design-system and component-library ADR — both should be made together and deliberately, not by stack default.

Curation workstream (parallel)

Software v0 can land without Sweetwater-grade facet coverage. But credible demonstration to industry requires real data. Curation work runs in parallel:

Define the v0 facet set per category (likely 10–20 facets per category across Electric Guitars, Pedals & Effects, Drums, and Print Music).
Pull canonical values from supplier data + Sweetwater reference.
Manual review for spelling, value normalisation, alias merging.
Document the curation process so future categories can follow the same shape.

This is content work, not engineering. Tyler + Greg, on their own time. Software v0 can demo with thin coverage; presentable v0 needs the curation done.

Success criteria

v0 is "done" when:

Three deliberately-varied distributors are ingested through saved mapping configs.
The canonical layer holds prioritised facets across the four v0-priority categories (Electric Guitars, Pedals & Effects, Print Music, Drums), with the full Sweetwater-derived starter taxonomy loaded for category mapping.
Two retailer profiles produce shape-correct output (Cin7 CSV + Shopify CSV) from the same canonical records.
Adding a third retailer profile (JBM) is purely a transformation config + category-mapping exercise — no canonical-record changes required. JBM proves operational diversity (per-retailer categories, mappings, brand mix, catalogue scale); format diversity is already proven by the Cin7 + Shopify dual-output mapping.
The admin UI is functional enough to demonstrate the workflow end-to-end to a non-technical viewer.
A read API exists and returns canonical records.

These are demonstration criteria, not sales criteria. v0 ships when it's showable, not when it's sellable.

What v0 deliberately learns

Whether the layered design holds under realistic supplier variability.
Where the transformation editor's complexity sits — what's easy, what's hard, what users will struggle with.
Bootstrap cost for the facet/taxonomy curation workstream.
Which canonical-layer governance decisions need policy and which can be deferred.
What real retailers say when shown the working system (post-build conversations with GMI, possibly AMA-level contacts).

What v0 doesn't try to learn

Pricing / commercial willingness (separate post-v0 conversation).
Supplier participation in a centralised platform (APIC supplier meeting and follow-up work).
Multi-retailer adoption dynamics (post-v0 outreach).
Scaling characteristics under load.

Open decisions (deferred to platform repo)

These are implementation choices that don't change the scope above. They belong in the platform repo's first ADRs:

Specific stack (language, framework, database).
Storage model for canonical records (relational, document, hybrid).
Transformation editor implementation pattern (form-based, expression-based, JSON-config).
Hosting / deployment posture.
Data migration discipline.
Design system / component library choice, and the specific visual reference benchmark (the "Design quality bar" section asserts the kind of bar; the specific pick is made here, paired with the design-system choice).

Suggested next step

Platform repo handoff — this scope memo is the brief. Implementation conversation moves there.
Curation workstream in parallel — facet set definition for the four v0 categories. Content work, not engineering.