How this was built

Built primarily with Claude Code (Anthropic's agentic coding tool), under direct human direction — the architecture, specification, and review decisions are the operator's; the AI generates code against that spec. The output is conventional TypeScript, Astro, and React — standard, maintainable code, not a proprietary format tied to the tool that helped write it. Quality claims here aren't self-assessed: every one is backed by an automated, regenerating verification ledger, not a status doc — see Verified Throughput. For a structured engineering review, see Code Review.

Bringing a new team up to speed

This is a subscription billing engine built for BigCommerce merchants — recurring charges, dunning (retrying failed payments), and a customer self-service portal, integrated into BigCommerce's own admin and storefront rather than running alongside it as a separate system. If you're picking this up cold, this page is the fastest path from zero to productive.

Before any estimate: what's the actual ask?

This page assumes none of the following are decided yet — confirm which applies before scoping any timeline or team size: (a) full path-to-GA delivery, (b) closing a specific named gap (see Known Limitations below), (c) the B2B Edition extension (approval workflows, purchase orders), or (d) integrating the BC Payments rail once partner-track access clears. Each is a different-sized engagement.

Where to start

Code review

Repo access, orientation map, runnable checks, known limitations

Architecture

Data model, state machine, BC platform integration seams

Live system

Touch the real thing day one — admin + storefront, no install

Stack map

Surface	Stack	Deployed on
apps/api	Cloudflare Workers + D1 — the charge/subscribe/dunning/cancel money path	Cloudflare Workers
apps/admin	React + BigDesign (BigCommerce's own design system)	Cloudflare Pages
apps/storefront-svelte, apps/storefront-catalyst	Two storefront integrations — Svelte (the live demo) and Catalyst (BC's headless React stack)	Cloudflare Pages
apps/portal	Astro — this site; internal/stakeholder communication, not part of the shipped product	Cloudflare Pages

Full rationale: Architecture

Things that will trip you up

Two storefront implementations exist (Svelte and Catalyst) — confirm which one your scope actually targets before estimating; they aren't interchangeable.
prototype/ is design reference, not production code — it informed the shipped design but isn't part of what runs. Don't sample it for a code-quality read.
The GA payment rail (BC Payments) is partner-track, not yet integrated. Today's live demo runs on Stripe sandbox — gateway-agnostic by design, but BC Payments access is an external dependency to size separately, not something this codebase can unblock on its own.
Canonical spec docs (PRD, BRD, Architecture) cross-reference internal decision records by ID (e.g. "ADR-0037") — each is hyperlinked to its actual content, so click through rather than treating the ID as something you need to already recognize.

Known limitations

16 acceptance criteria across 10 epics don't have a passing automated scenario yet — named, not estimated. Full list, grouped by area: Code Review.

Run the whole thing — day one

No single composed command starts every app — they're loosely coupled and mostly run independently. Below is the documented bootstrap plus the two apps most relevant to a first day (API + admin, wired together). Full detail, including the prototype-only fast path and per-app port list, is indocs/runbooks/local-dev-env.md.

git clone git@github.com:nino-chavez/bc-subscriptions.git
cd bc-subscriptions
git config core.hooksPath .githooks   # one-time per clone
npm install

# Terminal 1 — API (Cloudflare Workers, emulates D1/KV/R2/queues locally)
cd apps/api
npx --yes wrangler@4 d1 migrations apply subs-api-d1 --local --persist-to .wrangler/state
npx --yes wrangler@4 dev              # → http://localhost:8787

# Terminal 2 — admin, pointed at the local API
cd apps/admin
API_URL=http://localhost:8787 npm run dev   # → http://localhost:3000

Fastest cold-start path if you only need the design reference (no cloud access required):cd prototype && npm install && npm run dev→ http://localhost:5174. Operator-only credentials (Cloudflare API token, BC sandbox creds, GH workflow_dispatch) are not needed for any of the above — only for deploys and BC-sandbox integration testing.

Integrate

API reference

REST endpoints, scopes, webhooks, error shapes — the OpenAPI contract

Component library

team access

Storybook — separately credential-gated, own Cloudflare Pages deployment

@bc-subscriptions/reactrepo · team access
Hooks + components for subscription PDPs, cart, and account portal.
@bc-subscriptions/storefront-catalystrepo · team access
BigCommerce Catalyst bindings — server actions, storefront-framework queries, route handlers pre-wired for subscriptions.
@bc-subscriptions/storefront-webcomponentrepo · team access
Framework-agnostic custom element for Stencil and other non-React storefronts.
@bc-subscriptions/design-tokensrepo · team access
OKLCH-based tokens, framework-agnostic CSS variables. Tailwind preset + raw CSS exports.

Decision log: Decisions

Day-one checklist

Get real repo read access (the operator arranges this directly — see Code Review for what "real access" means here).
Touch the live system before reading a line of code — the demo is faster ground truth than any document.
Run the test suite and typecheck yourself (commands at Code Review) — confirm the same pass/fail state this page implies.
Read Architecture for the data model and integration seams before writing any code.
Confirm scope against the four options above before sizing anything.