BigCommerce engineering alignment

How this project intentionally tracks BC engineering conventions, design systems, deployment models, and the public platform contract. Counts derive from _state.json + ADR frontmatter.

BigEng conventions (catalogued)

12 rows · 12 compliant · ratified by ADR-0030

  • compliant
    bigeng-01-snake-case-wire

    snake_case wire fields — JSON request/response keys are snake_case on the wire

  • compliant
    bigeng-02-store-id-in-payload

    store_hash present as payload field, not header-only

  • compliant
    bigeng-03-offset-cursor-pagination

    Offset + cursor pagination, mutually exclusive — bigeng convention #3

  • compliant
    bigeng-04-typed-errors

    Typed domain ADTs for errors (vs ad-hoc { error: string } shapes)

  • compliant
    bigeng-05-principal-envelope

    Auth principal envelope {id, type} on requests

  • compliant
    bigeng-06-uuid-owned-entities

    UUID for owned entities; integer for legacy BC FKs

  • compliant
    bigeng-07-soft-delete-flag

    Soft-delete via is_deleted INTEGER (vs hard-delete + cascade)

  • compliant
    bigeng-08-timestamp-defaults

    TIMESTAMP DEFAULT CURRENT_TIMESTAMP on created_at / updated_at columns

  • compliant
    bigeng-09-operations-ledger

    Operations-table saga ledger (replaces inline cron-driven orchestration)

  • compliant
    bigeng-10-scope-entitlements

    Scope / resource entitlements (per-subscriber, not just store-wide)

  • compliant
    bigeng-11-audit-decorator

    Audit emission via decorator wrapping (vs inline INSERT INTO events)

  • compliant
    bigeng-12-audit-payload-shape

    Audit payload shape — target/resource/summary/operation_type + request-scoped MDC

ADR commitments traced into substrate

29 ADR-derived capability rows · 22 compliant

  • compliant
    adr-0007-uninstall-sweep

    ADR-0007: GDPR-driven uninstall retention sweep (30-day tombstone before hard delete)

  • compliant
    adr-0009-tenant-scope-guards

    ADR-0009: tenant data isolation via store_hash scope guards on every owned-entity read

  • compliant
    adr-0011-failed-permanently

    ADR-0011: failed_permanently terminal state — scheduler ratchets stuck charges

  • compliant
    adr-0014-typed-error-format

    ADR-0014: typed-error wire format (couples with BigEng convention #4)

  • compliant
    adr-0024-per-instance-overrides

    ADR-0024: per-delivery-instance override mutation API (skip / swap_product / reschedule_to)

  • compliant
    adr-0028-eligibility-engine

    ADR-0028: eligibility-engine architecture pattern (Epic 26 inclusion + exclusion rules)

  • compliant
    adr-0029-marketplace-first

    ADR-0029: marketplace-first, native-ready posture

  • compliant
    adr-0030-bigeng-alignment

    ADR-0030: BigEng pattern alignment — ratify the 12-convention catalog

  • non-compliant
    ops-ledger-max-attempts

    ADR-0031: operations.max_attempts column for per-row retry budget

  • partial
    ops-ledger-locked-until-reaper

    ADR-0031: operations.locked_until column + reaper cron

  • compliant
    job-configuration-table

    ADR-0031: job_configuration sidecar table for per-cron per-store config

  • compliant
    deprecation-handler-registered

    DeprecationRegistry + middleware wired at app boot (ADR-0032)

  • compliant
    api-version-namespace-v1

    All API routes mounted under /api/v1/ prefix (ADR-0032)

  • compliant
    deprecation-headers-emit-on-request

    Deprecation, Sunset, Link headers emit on deprecated route calls (ADR-0032)

  • compliant
    subscription-extensions-table

    ADR-0033: polymorphic subscription_extensions substrate for Epic 6 extension types

  • compliant
    extensions-scheduler-hooks

    ADR-0033: scheduler invokes extension lifecycle hooks before each renewal

  • compliant
    processor-adapter-bc-payments-production

    ADR-0035: BC Payments standard-rail adapter — production branch implemented (PAT mint + method lookup + payments.bigcommerce.com charge; throw at bc-payments.ts:70 replaced)

  • partial
    processor-adapter-bc-payments-webhook-extraction

    ADR-0035: BC Payments stored-instrument extraction at order.created webhook — real BigPay token persisted via GET /v3/customers/{id}/stored-instruments

  • compliant
    processor-adapter-stripe-production

    ADR-0025: Stripe secondary-rail adapter — production branch implemented (PaymentIntent.create with off_session MIT; no pre-existing BC order required)

  • compliant
    processor-adapter-stripe-decline-classification

    Stripe adapter classifies hard vs soft declines via HARD_DECLINE_CODES set; StripeChargeError exposes isHardDecline for scheduler dunning logic

  • + 9 more — see /prd for the full catalogue

BC-aligned architectural decisions

8 of 63 ADRs reference BC platform patterns directly

Design language

Three languages, ratified 2026-05-20: Shell (admin / portal — uses @bc-subscriptions/ui + design-tokens), Storefront (catalyst + svelte surfaces — BC storefront-kit aligned), BigDesign (confined to /prototypes/<name>/* slices). See ADR for three-language-design-contract.

Deployment model

Phase 1: Cloudflare Workers (apps/api) + Cloudflare Pages (admin, portal, storefronts, demos, program). Phase 2: GCP — Cloud Run + Cloud SQL Postgres + Memorystore + Pub/Sub + Secret Manager (ADR-0030 cloud-agnostic; ADR-0054 Cloud SQL Postgres; dms-self-serve reference pattern).

Marketplace posture

Marketplace-first, native-ready (ADR-0029). Ships as a marketplace app destination — not a waypoint — with native-graduation as design constraint, not commitment. Marketplace-blocking attestations tracked in / tile #2.

Internal docs corpus

2,665 pages of BC internal engineering docs sit at docs/rag/bc-internal-docs/ — architectural-fit reference for subscription-adjacent domains. See /inputs.