Skip to content
SiteSwarm Platform Documentation

Data Storage Pattern

Data Storage Patterns & Tenant Isolation

1. Executive Summary & Core Storage Patterns

SiteSwarm’s storage patterns align with its capability hosting model (CAPABILITY_MANAGEMENT.md) while avoiding unnecessary worker sprawl:

  1. App-Hosted Storage (app-hosted — Dedicated Per-Client Resources):
    • Direct Binding on the Client Worker: When an app-hosted or custom capability is lightweight and does not warrant the overhead of a separate Cloudflare Worker, the client application worker (apps/<client>) can bind directly to its dedicated Cloudflare D1 database or R2 storage—provided doing so does not bloat the worker bundle or interfere with our edge caching and content-serving strategy (APP_SERVING_CACHE.md).
    • Isolated Backing Service Worker: When an app-hosted capability carries heavy dependencies or an administrative studio (such as the client’s CMS), the dedicated D1 and R2 bindings attach to a separate app-hosted service worker invoked over a Cloudflare Service Binding (MULTI_WORKER_PLATFORM_SERVICES.md).
  2. Platform-Hosted Shared Storage (platform-hosted): Central platform services that client applications plug into via Service Bindings (such as Critiques) manage state in shared platform storage partitioned by verified tenant_id.
  3. Enterprise External Storage via Cloudflare Hyperdrive (Anticipated Future Pattern): While no active clients use this model yet, we anticipate that future clients bringing pre-existing external databases (e.g., PostgreSQL) will connect via Cloudflare Hyperdrive for edge connection pooling and query caching.
flowchart LR
    ClientWorker["Client Public Worker\n(apps/<client>)"] -->|"Direct Binding\n(Lightweight App-Hosted / Custom)"| DirectStore["Dedicated Client D1 / R2"]
    ClientWorker -->|"Service Binding\n(Heavy App-Hosted, e.g. CMS)"| AppService["App-Hosted Service Worker"]
    AppService --> AppStore["Dedicated Client D1 / R2"]
    ClientWorker -->|"Service Binding\n(Platform-Hosted)"| PlatService["Shared Platform Worker"]
    PlatService --> PlatStore["Tenant-Partitioned Storage"]

2. Core Storage Invariants

  1. Preserve Edge Caching & Fast Serving: Any direct storage binding on the public client worker must remain compatible with our edge caching and content-serving strategy (APP_SERVING_CACHE.md); heavy administrative or mutation-heavy workloads belong behind Service Bindings.
  2. Tenant Scoping on Shared Services: All multi-tenant queries in platform-hosted services require parameterized statements scoped by verified tenant_id.
  3. Data Integrity & Built-in Recovery: Cloudflare D1 provides continuous 30-day Point-in-Time Recovery (PITR) for tenant databases, and client data can be exported cleanly at any time via the offboarding procedure in CLIENT_OFFBOARDING.md.