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 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) |
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.