Reference index
Why this chapter exists
Every fact in MerchOS has exactly one canonical source (CLAUDE.md §1.6). This chapter is the map to those canonical sources, organized so a new engineer can answer “where do I find X?” in under 30 seconds.
This is not a duplicate of the underlying record — it’s a router. The canonical sources change; the router updates as part of the chapters above (each chapter ends with its own Canonical sources footer that updates alongside the chapter).
Root documentation
| File | What’s there |
|---|---|
CLAUDE.md | The 11 behavioral rules, the canonical-source map, the 9 verticals, the OnboardingStatus state machine, the 5 user roles, the 8 critical business rules. Read in full at session start. |
STACK.md | Source of truth for all dependencies + cloud accounts. |
DESIGN.md | Storefront + admin theming spec; BrandKit fields; per-portal theme rules. |
DECISIONS.md | The ADR index. |
docs/PHASES.md | The phase ledger. 1,156 lines as of 2026-05-19. |
docs/DOD.md | Definition of Done checklist. |
docs/PROMPTING.md | Prompt patterns (for David). |
POST_DEPLOY_BACKLOG.md | Post-launch build queue + deferred-deviation tracking. |
LAUNCH_CHECKLIST.md | Pre-launch operator checklist. |
FIRST_ORDER_RUNBOOK.md | First-real-customer end-to-end walk + 168-line Printful supplement. |
Service notes (per-module deep reads)
Each module under apps/api/src/modules/ has a corresponding deep-read note under docs/services/. Maintained per the CLAUDE.md §1.9 service-note accumulation rule.
Index: docs/services/INDEX.md. 20 notes covering all 22 modules (the four “small” modules — feature-flags, turnstile, analytics, health — share one combined note).
Most-relevant when:
| Module note | Read when |
|---|---|
auth.md | Touching JWT, magic links, password reset, cross-portal auth |
billing.md | Touching Stripe, tier swap, invoice cron, store credit |
brand-scraper.md | Touching Brandfetch + Claude pipeline |
catalog-pipeline.md | Touching Raw / Inbox / Master / Verticals services |
companies.md | Touching Company lifecycle, spend settings, BrandKit |
fulfillment.md | Touching multi-supplier routing, FulfillmentTask, webhooks |
mockups.md | Touching the sharp compositor, mockup pipeline, ProductMockup |
onboarding.md | Touching the state machine, wizard, transitionTo |
orders.md | Touching submit, refund, anonymous, MEMBER_PAYS, split-tender |
products.md | Touching Product CRUD, catalog-browser, per-vertical curation |
print-files.md | Touching the designer queue, DesignTicket flow |
suppliers.md | Touching Gelato / Printful syncs, mappings, raw mirror |
Operational runbooks
All under docs/operations/ — 9 runbooks. Each is intentionally short + intentionally specific.
| Runbook | When to read |
|---|---|
db-connection.md | pgbouncer session-mode rationale; debugging transaction-mode regressions |
db-recovery.md | PITR restore procedure; data-loss event |
fly-deploy-strategy.md | Deploy hangs / health-check polling timeout |
integration-tests.md | Writing a *.int.spec.ts or debugging an existing one |
migration-lock-recovery.md | Stuck Prisma migration lock (pg_locks objid=72707369) |
r2-cors-config.md | Cloudflare R2 bucket CORS issues |
sentry-setup.md | Sentry config / DSN rotation |
tier-swap-compensation.md | Tier-swap rolled back; manually compensate Stripe |
uptime-monitoring-setup.md | Uptime monitor not paging |
Architectural Decision Records
86 ADRs at the time of writing. Full index: docs/adr/ (or DECISIONS.md for the curated index).
The ADRs you’ll touch most often as a new engineer:
Foundation (read first when onboarding)
- ADR-0046 — Documentation reset (2026-04-25). The reason the current
CLAUDE.mddiscipline exists. - ADR-0049 — Vertical seeding canonical form.
- ADR-0091 — Wizard intake + activation invariants. Day-1 onboarding flow.
- ADR-0117 — This handbook’s own ADR. Maintenance contract for the chapters.
Pricing + billing
- ADR-0073 — Tier swap (Stripe-first ordering).
- ADR-0094 — MEMBER_PAYS family.
- ADR-0099 — Current tier ladder.
- ADR-0104 — Split-tender (Phase 0141).
- ADR-0106 — Per-pricing-model billing page.
- ADR-0108 — Post-activation re-classification (Accepted; build deferred).
- ADR-0114 — Stripe Tax + onboarding-state invariants.
Catalog pipeline
- ADR-0070 — Raw Catalog UI architecture.
- ADR-0071 — Per-vertical print-option curation.
- ADR-0077 — The axis model (color, size, print as separate tables).
- ADR-0079 — Editable YcmCategory.
- ADR-0080 — Cross-supplier identity rules.
- ADR-0089 — Launch readiness 12-check.
- ADR-0115 —
SkuVariantCellStateadditive override. - ADR-0116 — Mapping-table rebuild.
Supplier integration
- ADR-0068 — Gelato Raw Catalog mirror architecture.
- ADR-0078 — Platform-currency alignment.
- ADR-0081 — Unified supplier-ingest pattern.
- ADR-0084 — Printful onboarding + multi-supplier order routing.
- ADR-0085 — Printful URL-key webhook auth.
Storefronts + commerce
- ADR-0052 — Cross-portal password reset.
- ADR-0061 — Vibrancy gate for admin portal theming.
- ADR-0065 —
allowsGivesBack+ fundraising-markup hygiene. - ADR-0098 — Storefront narrative + trust elements.
- ADR-0113 — Multi-print-option intake.
Operational
- ADR-0103 — Pre-revenue reliability (PITR + synthetic monitoring + migration shadow-replay).
- ADR-0072 — Internal-admin guidance system.
Key migrations
Migrations that establish load-bearing facts (referenced from multiple chapters):
| Migration | What it establishes |
|---|---|
20260425_seed_canonical_verticals_and_suppliers/migration.sql | The 8 original verticals + their defaults |
20260511_phase7a_departments_and_member_pays/migration.sql | Departments vertical + MEMBER_PAYS family |
20260519c_phase0141_split_tender_schema/migration.sql | Split-tender schema (Phase 0141) |
Key memories
Operator memories (under memory/) that capture durable context not in the code:
| Memory | Why it matters |
|---|---|
tax_registration_pending.md | CRA GST/HST registration is in progress; until it lands, Stripe applies 0% to CA shoppers |
webhook_secrets_todo.md | Stripe webhook secret resolution status |
gcp_org_migration.md | Google Places API project owned by personal account; orphan risk if not migrated |
engineering_values.md | ”We ship enterprise code, no shortcuts, build for scale.” Bar to apply on every recommendation |
How to find something not listed here
When you don’t know where to look:
- For a code fact —
grep -rn '<symbol>' apps/api/src(or the relevant app). - For an enum / schema fact — open
prisma/schema.prisma. - For a decision — search
docs/adr/by topic. - For a phase + date —
git log --oneline --grep="<keyword>"or scandocs/PHASES.md. - For a service-level behavior — open the matching
docs/services/<module>.md. - For an operational issue —
docs/operations/<runbook>.md. - For a queued post-launch build —
POST_DEPLOY_BACKLOG.md.
Per CLAUDE.md §1.5: don’t write prose paraphrases of these sources. When you find a fact, link to it. The handbook stays a router, the canonical sources stay singular.
Triggers for update
Update this chapter if you:
- Add or retire a root-level documentation file.
- Add or retire a
docs/services/<module>.mdnote. - Add or retire a
docs/operations/<runbook>.md. - Add an ADR that becomes “foundational” enough to land in the curated list above (rare — most ADRs stay in the full index).
- Add a load-bearing migration referenced from multiple chapters.
- Add or retire a memory file that captures durable operator context.