Orientation — every surface, one page¶
Generated from a canonical source
This page is a read-only projection of docs/ORIENTATION.md.
Edit the canonical file, then run npm --prefix tools/project-knowledge-derive run derive.
What this is. The map of the BigCommerce-native subscriptions initiative: what exists, where it lives, and which door to walk through for which question. Use it to open a meeting, prime a stakeholder, or onboard a team. Every URL below is live.
The 30-second version. One product (a BC-native subscriptions engine), proven by a live demo store moving real sandbox money, documented on two doc faces (public product docs; a stakeholder knowledge base), narrated by one portal that routes every audience to the same facts at the right altitude.
The reading spine (inside this knowledge base)¶
You're at the front door of the stakeholder KB. It's one spine — front door to reference — and the left nav walks it in order:
- Understand — the system's shape at review altitude: the system in one picture, product spec, strategy, architecture (C4, flows, ERD — rendered), the BC API surface, how money moves, the event backbone, the delivery fork.
- Capabilities — how each capability actually works, honestly: the handoff corpus — 17 deep-dives, each with a typed honest-gap section.
- Decisions & review — the review instrument's own artifacts: the decision register, platform gaps & contract, and the open-decisions capture.
- Reference — test strategy (the five-gate ladder) and the internal glossary.
Running a solution review? Walk six pages in order: the system in one picture → decision register → how money moves → the event backbone → platform gaps & contract → open decisions. That's the whole review — the decisions and the honest gaps sit beside the capability deep-dives they reference, not in a separate package.
The doors, by what you're trying to do (Diátaxis)¶
| You want to… | Mode | Go to |
|---|---|---|
| See it work — touch the product before reading a word | Tutorial (learn by doing) | Live demo — admin + storefront, no install · Kibble & Co. demo shop · 43-step visual walkthroughs |
| Do a task — install, integrate, operate | How-to | Merchant guides (plans, dunning, promotions, settings) · Developer integration (Stencil, headless, Catalyst, testing) |
| Look something up — API, terms, data model, decisions | Reference | API reference + OpenAPI · Glossary · Data-model ERD · ADR log |
| Understand it — why it's shaped this way, what's real vs intended | Explanation | Product spec · Strategy · Architecture · Handoff corpus — 17 capability deep-dives, each with a typed honest-gap section |
The doors, by question¶
| Question | Answer lives at |
|---|---|
| What is this product? (features, positioning) | Portal → Product · Product spec (the PRD, rendered) |
| What's the tech stack / architecture? | Portal → Engineering · KB → Architecture (C4, sequence diagrams, flows, ERD, integration topology — all rendered) |
| How is it tested? What does "verified" mean here? | Test strategy (the five-gate ladder) · Trajectory (derived: what's proven, in flight, remaining) · per-capability detail: Capability status |
| Where are the user stories / requirements? | The BRD (repo: BRD.md, 28 epics · 218 stories · acceptance criteria; per-epic derived views under docs/audits/derived/brd-epics/). Repo access is operator-arranged; the Product spec carries the product surface without repo access |
| What's left to GA? (sizing an engagement) | Portal → Handoff — scoping block + the derived "What's left to GA" register |
| How does capability X actually work, honestly? | Handoff corpus — pick the domain; every page: what it's for → how it works → where intent and reality diverge (typed, cited) → how to operate & extend |
| What was decided, and why? | Decisions (84+ ADRs) · ask in prose: "Ask the substrate" chat on any portal page |
| What's the commercial story? | Portal → Sales · Strategy briefs (per-persona one-pagers) |
| How does this integrate with the BC platform today? What are the dependencies? | Platform integration & dependencies below · Integration topology (generated from deploy config + code) |
Platform integration & dependencies¶
Shape today: a BigCommerce marketplace app. OAuth install per merchant; the admin UI loads as a control-panel App Extension; all platform reads/writes ride public APIs (v3 REST, Storefront API); webhooks flow in both directions; the app owns its own runtime and data store (Cloudflare Workers + D1 today; GCP is the named Phase-2 substrate per ADR-0030). Nothing depends on BC-internal APIs.
Payments: recurring charges ride BC Payments' stored-instruments vault (ADR-0037). The app never sees card data — zero PCI scope — and merchant-initiated recurring charges are proven end-to-end on a real sandbox store.
Dependencies to watch:
- Stored-instruments access at install — new app registrations hit a PCI-scope confirmation gate before install completes; clearing it is a BigPay-side approval, not a code change.
- Uninstall semantics — BC auto-revokes the OAuth token and webhooks before the uninstall callback fires; offboarding is designed around that ordering.
- Webhook signing identity — BC signs webhooks with the
client_secretof the OAuth client that registered them; multi-store deployments key verification per merchant, not per app. - Capture timing — charge capture is auth+capture atomic today; EU merchants will eventually need a capture-on-ship split (known, tracked gap).
Bolt-on vs first-class: graduating from marketplace app to native platform citizen is an open, written-up question — the delivery fork, the native-shape gap matrix (what changes if a pod takes it in-platform), and the portability inventory (what carries over regardless). Short version: ships as a marketplace app, native-ready by design — specs, scenarios, and BC-platform contracts are substrate-independent.
URL inventory¶
| URL | What it is | Audience | Access |
|---|---|---|---|
| subs-portal.pages.dev | The portal — start here. Role lanes, live demo, KB, internal dashboards | Everyone | Public (currently ungated) |
↳ /kb |
Stakeholder knowledge base (MkDocs): spec, strategy, architecture, test strategy, handoff corpus | Stakeholders, delivery teams | With portal |
↳ /try |
Live system: demo admin + storefront + walkthroughs | Everyone | With portal |
↳ /design |
The original UX prototype (design reference, not production) | Design, product | With portal |
↳ /internal (Review) |
Build-verification dashboards (gates, coverage, open items) — internal vocabulary | Build team | With portal |
| docs.bcsubs.dev | Public product documentation — merchant guides, developer integration, reference | End users: merchants, developers | Public |
| kibble-headless.bcsubs.app | Kibble & Co. — the live demo storefront (real BC sandbox store, real Stripe-sandbox money) | Demo audiences | Public |
| admin.bcsubs.dev | The merchant admin app (the actual product UI) | Demo / evaluation | Public (demo store) |
| api.bcsubs.dev | The live API worker (production engine for the demo store) | Integrations | Public API surface |
| storefront.bcsubs.app | Storefront integration worker (Svelte) behind the demo shop | Infrastructure | Public |
| marketing.bcsubs.app | Marketing site prototype (capabilities, interactive demos) | GTM | Public |
| subs-portal-storybook.pages.dev | Component library (Storybook) | Implementation teams | bc-blueprint / bcb001 |
GitHub nino-chavez/bc-subscriptions |
The repo: code, BRD/PRD, ADRs, tests, tooling | Engineers | Private — operator-arranged |
Environments: production surfaces above deploy from main (operator-gated releases).
dev.subs-portal.pages.dev is the integration preview — work lands there first;
expect it to be ahead of, and occasionally rougher than, prod.
Money reality: the demo store runs on a real BigCommerce sandbox with Stripe test-mode underneath. Charges, renewals, dunning, and refunds are real system behavior with sandbox money — nothing touches a live card.
Priming a team in one meeting (suggested walk)¶
- Portal home — pick-your-lane framing (2 min)
- /try — touch the live product before any document (5 min)
- /handoff — scoping question + what's-left-to-GA register (5 min)
- One handoff-corpus page relevant to the team — show the honest-gap section; set the expectation that every capability has one (5 min)
- Route by role for homework: merchants/devs → docs.bcsubs.dev; architects → KB architecture; execs → Sales + Trajectory
Everything on this page is generated or derived from the repo and re-verified on
deploy; where a claim can drift, a CI gate covers it. Source: docs/ORIENTATION.md.