Data Architecture

Current Shape

The repository uses a Cloudflare-native architecture with Workers, D1, Durable Objects, R2, Queues, multi-D1 tenant data, domain workers, and peer-fork UI surfaces (CLAUDE.md:14-23).

Tenant-scoped Worker environments can expose config, ops, and customer D1 bindings through the shared tenant binding helpers (workers/_shared/tenant-bindings.ts:1-5).

The booking worker declares TENANT_CONFIG_DB and TENANT_OPS_DB D1 bindings and a booking presence Durable Object binding (workers/booking/wrangler.toml:5-22).

The auth worker declares a config D1 binding, an auth KV namespace, and token/session TTL variables (workers/auth/wrangler.toml:5-19).

The notifications worker declares a tenant ops D1 binding and provider secret variables for delivery channels (workers/notifications/wrangler.toml:8-18).

Gateway Context

The edge gateway resolves admin requests into catalog, booking, availability, reporting, events, queue, and staff-feed domain workers (workers/edge-gateway/src/router.ts:15-34).

The edge gateway resolves public branch, service, staff, company, booking, hold, checkout, customer, event, and queue requests into the appropriate domain workers (workers/edge-gateway/src/router.ts:37-51).

Top-level gateway routing sends auth, staff session, admin, public, webhook, Google sync, and control-plane paths to their service bindings (workers/edge-gateway/src/router.ts:54-89).

Downstream Worker requests receive tenant ID, tenant slug, company ID, tenant config DB ID, tenant ops DB ID, branch ID, home region, customer shard ID, and auth user headers from the gateway (workers/edge-gateway/src/router.ts:134-165).

Tenant resolution supports custom domain lookup, path slug lookup, API-key lookup, and auth-token tenant lookup with cache support and suspended/provisioning blocks (workers/edge-gateway/src/middleware/tenant-resolver.ts:6-205).

D1 Binding Helpers

The shared getD1Binding helper reads dynamic D1 binding names from the Worker environment and throws when a required binding is missing (workers/_shared/tenant-bindings.ts:28-36).

bindTenantDatabases attaches tenant config, tenant ops, and optional customer database handles to the request environment based on tenant context (workers/_shared/tenant-bindings.ts:38-67).

The shared ops-fanout helper in voyage is a capability primitive, not a fully wired runtime path: it needs an explicit shard-entry list and tags successful shard rows with _region, but it does not discover the regional bindings by itself (workers/_shared/ops-fanout.ts:1-78).

Customer fanout discovers CUSTOMER_NN_DB bindings, sorts them by shard number, runs SQL across customer shards, and tags returned rows with _shard (workers/_shared/customer-fanout.ts:1-85).

Meridian-Scale Topology Evidence

The Meridian reference fork's topology generator defines singleton config, customer-directory, reporting, and simulation databases, current regional ops databases, archive ops databases, and customer shard databases (../voyage-bank/scripts/generate-topology.ts:66-109, ../voyage-bank/scripts/generate-topology.ts:164-209).

The same topology generator validates exactly ten ops regions and exactly sixty-four contiguous customer shards from 0 through 63 (../voyage-bank/scripts/generate-topology.ts:141-160).

The reference tenant topology JSON lists ten ops regions: northeast, mid-atlantic, southeast, florida, midwest, texas, mountain, norcal, socal, and pacific-northwest (../voyage-bank/config/tenant/topology.json:3-64).

The reference tenant topology JSON lists customer shard entries from CUSTOMER_00_DB through CUSTOMER_63_DB (../voyage-bank/config/tenant/topology.json:65-130).

The topology generator currently includes archive year 2025, which produces archive ops D1 databases for that year (../voyage-bank/scripts/generate-topology.ts:64-64, ../voyage-bank/scripts/generate-topology.ts:173-209).

Reporting and Rollups

The reporting worker mounts reports, network, branch overview, activity monitor, workforce, queue operations, customer analytics, service catalog, resources summary, event campaigns, alerts, scoring, audit, scheduled reports, and rollup routes (workers/reporting/src/index.ts:31-46).

Network summary reads active branch and active staff counts from config data and daily aggregate metrics from reporting rollup tables (workers/reporting/src/routes/network.ts:21-153).

Region summary reads active region metadata, active branch mapping, branch facts, and sparkline facts from config and reporting databases (workers/reporting/src/routes/network.ts:156-230).

The current voyage reporting worker has the rollup route and expects a fanoutOps helper in request context, but its checked-in reporting middleware does not set fanoutOps or fanoutCustomers, so that cross-region path is not fully wired at this HEAD (workers/reporting/src/middleware/tenant-context.ts:1-34, workers/reporting/src/routes/rollup.ts:25-49).

The fully wired multi-region fanout implementation lives in the Meridian tenant fork: its reporting middleware injects fanoutOps and fanoutCustomers, its reporting worker mounts the same route families, and its rollup route executes against those helpers (../voyage-bank/workers/reporting/src/middleware/tenant-context.ts:1-55, ../voyage-bank/workers/reporting/src/index.ts:21-46, ../voyage-bank/workers/reporting/src/routes/rollup.ts:29-53).

The accurate current description is therefore per-tenant deployment composition: the platform repo provides route shapes and shard-fanout helpers, while the tenant fork wires those capabilities into the reporting runtime for a specific deployment (workers/reporting/src/routes/rollup.ts:25-49, ../voyage-bank/workers/reporting/src/middleware/tenant-context.ts:47-53).

Corrections From Frozen HTML

The frozen page's multi-D1 shape is still accurate, but current docs should name config, ops, yearly archive ops, reporting, customer-directory, and sixty-four customer shard databases where the Meridian reference fork proves them (../voyage-bank/scripts/generate-topology.ts:66-109, ../voyage-bank/scripts/generate-topology.ts:164-209, ../voyage-bank/config/tenant/topology.json:3-130).

The frozen page's shard-context description should include the current gateway headers for tenant config DB, tenant ops DB, branch, home region, customer shard, and auth identity (workers/edge-gateway/src/router.ts:134-165).

last verified: 2026-04-24 voyage HEAD: 14f3b190db8817399dcd30e1dc4e1ae7674bbf8a voyage-bank HEAD: ef4d7d4f9a66a05d68c265debc681d506a0606c6