Skip to content
SiteSwarm Platform Documentation

App Serving Cache

Edge Rendering, Static Content Delivery, Caching & Invalidation

1. Executive Summary

Client web traffic is overwhelmingly read-heavy, requiring fast global delivery of static assets and cached HTML while ensuring that when a business owner publishes an operational update from their phone, the change appears live globally in under 2 seconds without a CI/CD rebuild.

flowchart LR
    Visitor["Public Visitor Request"] --> Cache["Cloudflare Edge Cache"]
    Cache -->|"Cache HIT"| Fast:::plain
    Cache -->|"Cache MISS"| WorkerA["Client Public Worker (Edge SSR)"]
    WorkerA <-->|"Service Binding"| WorkerB["App-Hosted CMS Worker"]
    WorkerB -.->|"On Publish"| Purge["Platform Purge Service"]
    Purge -.->|"Evict Tenant Cache-Tag"| Cache


    Fast["Serve Immediately at Edge"]
    classDef plain fill:none,stroke:none;

2. Static Content Delivery & Rendering Boundaries

  1. Static Assets & Zero-Framework-JS Default:
    • Content pages ship with zero client-side framework JavaScript by default; interactive islands are strictly opt-in and deferred below the fold (client:visible / client:idle).
    • Web fonts (.woff2) and static files are served directly from public/assets/ at the edge (font-display: swap), avoiding third-party font CDNs and external network waterfalls.
  2. Edge SSR Shielded by Anycast Caching:
    • Non-CMS client sites may build as pure static output (output: "static").
    • CMS-enabled client sites run in Edge SSR mode (output: "server") shielded by Cloudflare Anycast edge caching (s-maxage, stale-while-revalidate, Cache-Tag).
  3. Fail-Safe Graceful Degradation (No Fabricated Fallbacks):
    • Public sites never bake fake operational notices or dummy specials into production code as “fallback seeds.”
    • Dynamic content slots rely on stale-while-revalidate and stale-if-error during transient upstream hiccups, or gracefully render nothing if an optional banner is absent.

3. Content Invalidation & Read Shielding

  1. Simple Tenant-Scoped Surrogate Tagging:
    • Edge SSR responses carry a tenant-scoped surrogate key (Cache-Tag: tenant:<client-slug>), avoiding brittle per-component tag bookkeeping.
  2. Sub-2-Second Cache Eviction & Purge Quota Protection:
    • When an owner publishes an update in their app-hosted CMS worker, the worker commits to D1 and invokes the platform-hosted purge service (@siteswarm/service-cache-purge, see MULTI_WORKER_PLATFORM_SERVICES.md) over a Service Binding to evict the tenant’s cache tag globally.
    • Centralizing purge requests through the platform service keeps Cloudflare Zone Purge tokens out of client workspaces and enforces per-tenant rate limiting and coalescing so a single client cannot exhaust the platform’s shared Cloudflare Purge API quota/bandwidth.
    • If a purge API call is throttled or experiences a transient failure, the content save still succeeds and caches refresh naturally within the stale-while-revalidate window.
  3. Single-Flight Stampede Defense:
    • On an edge cache miss under concurrent load, the public worker coalesces concurrent reads into a single in-flight request backed by a short in-memory micro-cache, protecting backing D1 databases from cache stampedes.