Native-shape gap matrix¶
Generated from a canonical source
This page is a read-only projection of docs/strategy/native-shape-gap.md.
Edit the canonical file, then run npm --prefix tools/project-knowledge-derive run derive.
Companion to: delivery-fork.md
Last updated: 2026-05-22
Source authority: docs/rag/bc-internal-docs/ (BigEng internal documentation, surveyed 2026-05-11)
The table below maps the substantive architectural dimensions where the current shape (Cloudflare/TypeScript marketplace app) diverges from what a BigCommerce native first-class service requires, per BC's published internal standards.
Rework cost legend: - S (small) — config / minor refactor, ≤ 1 engineer-week - M (medium) — substantial refactor but reuses domain logic, 1–4 engineer-weeks - L (large) — full rewrite of the dimension, 1–3 engineer-months - XL (extra-large) — discardable / not portable; the dimension is rebuilt from scratch in the new substrate
The matrix¶
| # | Dimension | Current shape (marketplace, today) | Marketplace-app target (Path A) | Native first-class target (Path B) | Rework cost A→B | BigEng source |
|---|---|---|---|---|---|---|
| 1 | Runtime | Cloudflare Workers (V8 isolates) | Cloud Run on GCP (Phase 2 per ADR-0030) | Nomad-scheduled containers in CDE or platform cluster; defined by .container.yml |
XL | infrastructure/deployments/containers.md |
| 2 | Language | TypeScript (Hono + Vitest) | TypeScript (unchanged) | Ruby (msms, BigPay precedent), Scala (api-proxy), or Java; never TypeScript on the backend | XL | services/merchant-subscription-manager-service.md, services/bigpay.md |
| 3 | Service interface | Our own REST API (apps/api) |
REST + GraphQL public surfaces | gRPC; proto definitions land in bigcommerce/interfaces |
XL | technical/standards/interfaces/protobuf-style-guide.md |
| 4 | Public API exposure | Our REST is the public surface | Hardened, versioned, OpenAPI-documented | We do not expose public APIs; api-proxy-java composes our gRPC into BC's /v3 and GraphQL |
XL | services/api-gateway.md |
| 5 | Data store | Cloudflare D1 (we own it) | Cloud SQL MySQL (we own it) | Tables in the shared BC store DB, partitioned by bounded context; never JOIN across contexts | L | technical/standards/bounded-contexts.md |
| 6 | Auth / request context | OAuth token issued per merchant install | Same | Internal protobuf request context: x-bc-request-context-bin, x-audit-principal-bin, OT trace IDs, store-hash, datacenter — all propagated via gRPC trailing metadata |
L | technical/standards/internal-services/context-propagation.md |
| 7 | Eventing | D1 outbox → Worker cron → BC webhooks (ADR-0010, ADR-0027) | Cloud Tasks / Pub-Sub equivalents | RabbitMQ via Domain Eventing system; events documented in bigcommerce/interfaces; consumers pull missing attrs via gRPC |
L | technical/standards/domain-eventing.md |
| 8 | Layering | App-shaped: Hono routes → handlers → D1 queries | Same | Strict Domain / Application / Infrastructure separation; Domain layer has no HTTP/network/serialization awareness; immutable cross-layer DTOs | M (domain logic ports; harness rebuilt) | technical/standards/layering.md |
| 9 | Bounded context discipline | We define our own bounded context (we own the DB) | Same | Subscription is one bounded context; cannot read Orders / Customers / Catalog tables directly; must call public interfaces of those domains | M | technical/standards/bounded-contexts.md |
| 10 | Payments / vault | Our bc-vault-client + portal routes wrap BC /v3/payments stored instruments (ADR-0037) |
Same | Direct gRPC into BigPay (bigcommerce/bigpay); no separate vault façade; BigPay owns the transaction storage |
XL (entire ADR-0037 substrate becomes vestigial) | services/bigpay.md |
| 11 | Transactionality | Eventual consistency across HTTP boundaries; producer-outbox for guarantees | Same | Sagas + 2PC patterns; transactionality within bounded context via DB transactions; cross-context via documented event contracts | M | technical/architecture/transactionality.md |
| 12 | Observability | Wrangler logs, Workers Analytics Engine, structured logs (ADR-0015) | + Sentry, custom dashboards | Lightstep traces (OT-Trace spec), logstash app_name, Sentry per-habitat (integration/staging/production), Prometheus auto-wiring, Grafana |
L | services/bigpay.md, services/merchant-subscription-manager-service.md |
| 13 | Deploy pipeline | wrangler deploy from GitHub Actions → Cloudflare Pages/Workers | GHA → Cloud Run | Launchbay → Nomad → habitats (integration / staging / production); canary + rollback first-class; .container.yml declares processes |
XL | infrastructure/deployments/strategies.md, infrastructure/deployments/containers.md |
| 14 | Secrets | Wrangler secrets + Cloudflare KV + gh secret |
GCP Secret Manager | HashiCorp Vault | S | infrastructure/deployments/secrets.md |
| 15 | Service mesh | n/a (Workers handle their own routing) | Cloud Run native | Consul Connect + Envoy sidecars | M | infrastructure/deployments/containers.md |
| 16 | Cluster placement | n/a | n/a | One of three: admin (admin-network accessible), payments (CDE), platform (default) — subscriptions likely lives in payments for PCI scope |
M (placement decision + PCI scoping) | infrastructure/deployments/containers.md |
| 17 | Storefront surface | Stencil widget injector + Catalyst SDK + Web Component (ADR-0013) | Same | Native storefront UI ships in BC's storefront-kit/Catalyst directly; no separate widget injection | L | (no direct internal doc; inferred from Catalyst storefront architecture) |
| 18 | Merchant control panel surface | App Extensions + iframe + our own admin app (ADR-0012) | Same | Native control-panel routes built with BigDesign in BC App or as native service-backed pages | L | (no direct internal doc; inferred from control-panel patterns) |
| 19 | Merchant audit log | Our own D1 audit_log table + emissions |
Same | BC's merchant-facing audit log surface (BigEng DoD Gate 3 requires this for native features) | M | docs/rag/sdlc-frameworks/bigcommerce-bigeng.md Gate 3 |
| 20 | Performance SLO | ≤ 800ms p95 for admin routes; ≤ 1.5s for write paths | Same | < 100ms p95 (BC API DoD); < 200ms TTFB for merchant-facing surfaces | M | docs/rag/sdlc-frameworks/bigcommerce-bigeng.md Gate 4 |
How to read the rework column¶
The column reflects cost if Path B is chosen as the target. Path A from current is mostly low-cost (the marketplace-app shape is already what we have; GCP migration is documented but not yet executed). The asymmetry matters: Path A protects most of the current investment; Path B treats most substrate-mechanic dimensions as discardable.
Aggregate rework profile, Path A → Path B: 9 XL, 6 L, 4 M, 1 S. Twenty distinct dimensions. Calling this "refactoring" understates it — it's a re-implementation with the current codebase serving as executable spec.
What survives even in Path B¶
These dimensions are zero or minimal rework cost regardless of fork (covered exhaustively in portability-inventory.md):
- Behavioral specifications (BRD, PRD, AC)
- Rail decisions documented as ADRs (capture timing, eligibility, idempotency, delivery-instance)
- Persona definitions and journeys
- Hive substrate and methodology
- Test scenarios (BDD-style behavioral assertions remain runnable against any backend)
- Design tokens and UI primitives (per surface — some, not all, would land in BigDesign)
The structural precedent¶
merchant-subscription-manager is the closest analog already operating inside BC: Ruby gRPC ambassador managing Zuora subscriptions for merchants (BC billing its customers). A shopper-facing subscriptions native service would parallel its pod structure — owned by a Payments-adjacent pod, integrating with BigPay rather than Zuora, exposing gRPC contracts via bigcommerce/interfaces, composed into public APIs by api-proxy-java.
Studying msms's repo (requires BC GitHub access) before Path B would be a Day-1 task.