Skip to content

System integration topology — bc-subscriptions (Phase 1, Cloudflare)

Generated from a canonical source

This page is a read-only projection of docs/architecture/integration-topology.md. Edit the canonical file, then run npm --prefix tools/project-knowledge-derive run derive.

@generated — mechanically parsed from infra/cloudflare/wrangler.toml (cron triggers, custom-domain routes), apps/api/src/types.ts (the Env secret/binding contract), and apps/api/src/adapters/*.ts (processor adapter modules) by tools/arch-derive/. Do not hand-edit — regenerate with npx tsx tools/arch-derive/derive.ts. CI (arch-derive-ci.yml) fails if the committed doc drifts from a fresh derive.

Anti-fabrication note. Every external integration below is grounded in a real secret name in the Env interface, a real adapter module, or a real route/cron declared in wrangler.toml. No non-Cloudflare-hyperscaler or message-broker edges are drawn — the planned Phase 2 migration per ADR-0030 is a future state, not the as-built topology this tool reads.

C4 legend. This is a flowchart-style rendering of a C4 container diagram (GitHub does not render Mermaid C4Container/C4Context blocks, so a plain flowchart stands in). Rectangles are containers (independently deployable units); cylinders are datastores; the diagram omits the C4 component layer. Person actors are drawn as ((...)) circles.

flowchart LR
  API["API + Webhooks Worker\napps/api (subs-api)"]
  BC_REST["BigCommerce REST / GraphQL / Storefront APIs"]
  BC_Payments["BC Payments vault\npayments.bigcommerce.com"]
  BCPaymentsAdapter["BC Payments adapter\nadapters/bc-payments.ts"]
  StripeAdapter["Stripe adapter\nadapters/stripe.ts"]
  AuthnetAdapter["Authorize.Net adapter\nadapters/authnet.ts"]
  BCWebhooks["Inbound BC webhooks\n(signed, verified via BC_WEBHOOK_SIGNING_SECRET / BC_CLIENT_SECRET)"]
  StripeWebhooks["Inbound Stripe webhooks\n(verified via STRIPE_WEBHOOK_SECRET)"]
  NetworkUpdaterWebhook["Inbound network-account-updater webhook\n(verified via NETWORK_UPDATER_WEBHOOK_SECRET)"]
  Sentry["Sentry\n(observability)"]
  Cron["Cloudflare Cron Triggers"]
  EventsQueue{{"subs-events Queue"}}
  EmailConsumer["Email Consumer Worker\napps/email-consumer (subs-email-consumer)"]
  Resend["Resend API"]

  API -->|REST/GraphQL, per-store OAuth token| BC_REST
  API -->|stored-instruments charge, ADR-0037| BC_Payments
  API --> BCPaymentsAdapter --> BC_Payments
  API --> StripeAdapter -->|Stripe API| Stripe["Stripe"]
  API --> AuthnetAdapter -->|Authorize.Net API| Authnet["Authorize.Net"]
  BCWebhooks -->|POST /webhooks/bc| API
  StripeWebhooks -->|POST /webhooks/stripe| API
  NetworkUpdaterWebhook -->|POST /webhooks/network-updater| API
  API -->|error/perf events| Sentry
  Cron -->|"* * * * *"| API
  Cron -->|"0 3 * * *"| API
  API -->|"produces, logEvent()"| EventsQueue
  EventsQueue -->|consumes| EmailConsumer
  EmailConsumer -->|transactional email| Resend
  API -.->|custom domain| Domain["api.bcsubs.dev"]

Integration secrets (apps/api/src/types.ts Env)

Env field Integration channel
BC_CLIENT_ID BigCommerce OAuth app identity
BC_CLIENT_SECRET BigCommerce OAuth token exchange + signed-JWT/webhook HMAC fallback
BC_API_TOKEN Worker-level fallback BC API token
CREDENTIAL_ENCRYPTION_KEY Per-store OAuth token / credential at-rest encryption (AES-256-GCM)
SSO_HANDOFF_SECRET Storefront-to-portal SSO handoff JWT (HS256)
BC_WEBHOOK_SIGNING_SECRET Inbound BC webhook HMAC verification (per-registering-client)
BC_STOREFRONT_TOKEN Sandbox-only fallback Storefront API token
STRIPE_WEBHOOK_SECRET Inbound Stripe webhook HMAC verification
NETWORK_UPDATER_WEBHOOK_SECRET Inbound network-account-updater (VAU/ABU) webhook HMAC verification