Client Content Management (CMS) & Mobile BAU Editing True Specification

Document Status: 🟢 Active True Specification
Target Audience: Core Engineering, Architecture Contributors, AI Agents
Primary Maintainer: SiteSwarm Architecture Council
Related Documents: HIGH_LEVEL_DESIGN.md, docs/PRD.md, docs/CAPABILITY_MANAGEMENT.md, docs/INGRESS_AND_PREVIEW_ROUTING.md, docs/DATA_ISOLATION_AND_STORAGE.md, ADR-0003
Implementation Tracking: Issue #28, Issue #65

1. Executive Summary & The Core Architectural Invariant

SiteSwarm is engineered for software engineers maintaining full-time daytime careers. For the business model to scale sustainably across dozens of local businesses, engineers must never be interrupted during daytime hours to perform routine content updates, and clients must never feel held hostage by an agency just to run their daily business operations.

A local bakery owner cannot wait hours or days for a developer to push a git commit just to post an 8:15 AM “Sold Out of Sourdough” banner, update holiday hours, or announce an emergency snow storm closure.

flowchart LR
    subgraph ClientDevice["Client Mobile or Desktop (<60s)"]
        A["Open client.com/admin\n(or /_emdash/admin)"] --> B["Cloudflare Access / Passkey Auth"]
        B --> C["EmDash Content Studio\n(Banners, Hours, Menus, Posts)"]
        C --> D["Tap 'Publish Now'"]
    end

    subgraph WorkerFleet["Decoupled Cloudflare Edge Fleet"]
        subgraph WorkerB["Worker B: Isolated CMS & Admin"]
            D --> E["EmDash Engine\n(Validation & Typed Schemas)"]
            E --> F["Cloudflare D1 + R2\n(Exclusive DB Binding)"]
            F --> I["Invalidation Bridge\n(Purge Edge Cache-Tags)"]
        end

        subgraph WorkerA["Worker A: Public Static Frontend"]
            I -.->|"Purge Tag (<150ms)"| G["Live Static Website\n(Sub-20ms TTFB, 0 KV, 0 KB JS)"]
        end
    end

    subgraph AgencyZeroLoad["Daytime Engineers"]
        H["Zero Tickets Filed\nZero Daytime Distractions\nZero Git Commits"]
    end

    G -.-> H

The Three Foundational CMS Invariants:

The 60-Second Mobile Benchmark: Any non-technical business owner must be able to open the admin interface on an iOS or Android smartphone and publish a mission-critical update in under 60 seconds.
The Zero-Lockout Mandate: Core operational CMS functionality (hours, emergency banners, daily specials, contact details) is always included and free forever in the base application. Clients are never locked out of operating their business if they pause or discontinue custom agency retainers.
The Blast-Radius Layout Invariant: Content data is strictly separated from layout code. A client cannot break site responsiveness, destroy accessibility (WCAG 2.1 AA compliance), ruin typographic hierarchy, or trigger runtime 500 errors through CMS edits.

2. Contender Evaluation & Technical Audit Matrix

To establish the definitive CMS strategy without reinventing the wheel or incurring runaway costs, we evaluated leading architectural patterns against SiteSwarm’s core criteria: edge compatibility, mobile usability, cold-start latency, hosting cost, and maintenance burden.

2.1 Comprehensive Contender Matrix

Evaluation Criteria	Contender 1: Strapi	Contender 2: Directus	Contender 3: Payload CMS v3	Contender 4: Git-Backed (Decap/Tina)	Contender 5: EmDash CMS (`emdash`)
Edge Worker Compatible?	❌ No (Node.js monolith)	❌ No (Node.js monolith)	⚠️ Yes (via OpenNext/D1)	🟢 Yes (Client-side SPA)	🟢 Yes (Native Astro/Worker)
Hosting Footprint	Dedicated VPS / Container	Dedicated VPS / Container	Serverless Worker + D1 + R2	Static Hosting (Pages)	Serverless Worker + D1 + R2
Infrastructure Cost	🔴 High ($5–$20/mo/client)	🔴 High ($5–$20/mo/client)	🟡 Moderate ($5/mo Workers Paid)	🟢 Near-$0 (Cloudflare Free)	🟢 Near-$0 (Free tier) to $5/mo (Fleetwide Paid)
Compressed Bundle Size	> 80 MB (Node runtime)	> 70 MB (Node runtime)	4 MB – 9 MB (Compressed)	< 1 MB (Client JS)	~1.5 MB (Full Astro Integration)
Edge Cold Start Latency	N/A (Server startup 5-15s)	N/A (Server startup 5-15s)	1,500ms – 3,500ms	0ms (Static asset)	100ms – 250ms
Live Propagation Delay	< 1s (API query)	< 1s (API query)	< 1s (D1 query)	🔴 60s – 180s (CI/CD build)	< 1s (D1 query)
Mobile & Desktop UX	🔴 Heavy desktop UI	🔴 Heavy desktop UI	🔴 Sluggish on mobile	🔴 Fragile GitHub auth	🟢 Responsive Astro + React Studio
Maintenance Burden	🔴 OS/Docker patches	🔴 OS/Docker patches	🟡 Dependency updates	🟢 Zero server upkeep	🟢 Zero server upkeep (Serverless)
Architectural Verdict	❌ REJECTED	❌ REJECTED	⚠️ Specialized Upsell Only	❌ REJECTED for Operations	🟢 OFFICIALLY ADOPTED UNIFIED CMS

2.2 Deep-Dive Contender Audits

2.2.1 Contender 1: Strapi (Investigated on Cloudflare Workers)

Architecture: Monolithic Node.js framework built atop Koa.
Can it run on Cloudflare Workers?: No. Strapi fundamentally relies on:
1. Node.js native filesystem access (fs, path) to generate schema files, configuration, and controller files at boot.
2. Dynamic require() statements and module loaders incompatible with V8 edge isolates.
3. Relational database ORMs (Knex / Strapi ORM) requiring persistent TCP socket connection pooling to PostgreSQL/MySQL, incompatible with stateless edge isolates without heavy proxy pooling.
4. Runtime memory footprints exceeding 250 MB at idle, exceeding Worker memory limits.
Cost & Maintenance Impact: Running Strapi requires provisioning and maintaining long-running container instances (e.g. Render, Railway, Fly.io, or DigitalOcean Droplets). For a fleet of 20 clients, this would cost between $100 and $400 every month in hosting fees alone, requiring ongoing Linux security patching, container healthcheck monitoring, and database management.
Verdict: ❌ REJECTED. Directly violates the near-$0 hosting invariant and the low-maintenance homelab/agency axioms.

2.2.2 Contender 2: Directus

Architecture: Node.js and Express dynamic API engine and administrative dashboard.
Can it run on Cloudflare Workers?: No. Like Strapi, Directus requires a persistent Node.js server environment and continuous database connection pooling.
Cost & Maintenance Impact: Running Directus across a multi-tenant client fleet demands dedicated Docker containers or a centralized multi-tenant database cluster with complex logical partitioning.
Verdict: ❌ REJECTED. Directly rejected based on user constraints to avoid dedicated servers that balloon infrastructure costs.

2.2.3 Contender 3: Payload CMS v3 on Cloudflare Workers

Architecture: Next.js full-stack framework deployed to Workers via @opennextjs/cloudflare, using @payloadcms/db-d1 and Cloudflare R2.
Worker Tier & Bundle Footprint:
- Cloudflare Workers Free tier has a strict 3 MB compressed script limit.
- Payload CMS v3 bundles (including Next.js runtime, Lexical editor dependencies, and GraphQL/REST routers) compress to between 4.5 MB and 8.5 MB.
- Therefore, deploying Payload CMS strictly requires the Cloudflare Workers Paid plan ($5/month).
Operational Reality & User Experience:
- While running Payload on Workers is technically feasible, the real-world performance trade-offs are significant.
- Edge cold starts range from 1.5 to 3.5 seconds due to the heavy bundle size and memory allocation.
- The Payload administration UI is an enterprise-grade, desktop-oriented React application. On mobile Safari or Chrome over cellular connections, loading the administrative bundle is sluggish (3–6 seconds for initial interactive paint), making rapid phone updates frustrating for non-technical clients.
Verdict: ⚠️ RESERVED FOR ADVANCED ENTERPRISE UPSELLS. Too heavy, slow, and complex for everyday mobile BAU updates across standard client sites.

2.2.4 Contender 4: Git-Backed Headless CMS (Decap CMS, TinaCMS, Keystatic)

Architecture: Client-side Single Page Application (SPA) authenticating against GitHub/GitLab and committing markdown/JSON directly to the Git repository.
Strengths: Zero database cost; all edits are auditable via Git commits; runs on static Cloudflare Pages.
Fatal Flaws for Mobile BAU:
1. Build Propagation Latency: When a client toggles an announcement banner or updates holiday hours, the change does not reflect live until GitHub triggers a webhook, runs CI, and deploys the new build (1 to 3 minutes). For emergency closures or daily specials, this delay causes confusion and repeated clicks.
2. Mobile Authentication Friction: Connecting non-technical business owners through GitHub OAuth or third-party OAuth proxies (e.g. Netlify Identity or custom worker bridges) frequently causes authentication loops and token expirations on mobile devices.
3. Git Concurrency Conflicts: If an AI agent or engineer is actively developing a feature branch while a client commits an hour change, branch drift and merge conflicts inevitably occur.
Verdict: ❌ REJECTED FOR BAU EDITS. Acceptable for long-form agency blog drafting, but completely unviable for emergency mobile notices.

2.2.5 Contender 5: EmDash CMS (Cloudflare + Astro + D1 + R2)

Architecture: Modern open-source CMS created specifically for Astro and built natively on the Cloudflare ecosystem (Workers, D1, R2).
Key Strengths:
1. Direct Stack Alignment: SiteSwarm client applications are authored in Astro. EmDash integrates natively with Astro’s component architecture rather than forcing a Next.js or React runtime.
2. Avoids Reinventing the Wheel: Provides a typed content engine, media management with R2, and a prebuilt administrative interface out of the box.
3. Sandboxed Worker Isolate Plugins: Features a security-first plugin system where plugins execute in isolated Cloudflare isolates with explicit capability permissions.
4. AI & Human Friendly: Features built-in Model Context Protocol (MCP) support, enabling AI coding agents to inspect schemas and manage content programmatically.
Considerations: Running full dynamic worker plugins requires Cloudflare Workers Paid ($5/mo), but this is account-level rather than per-site.
Verdict: 🟢 OFFICIALLY RECOMMENDED OPEN-SOURCE CMS FOUNDATION.

2.2.6 Evaluation Summary & Resolution

Prior Consideration: Early prototypes explored an agency-crafted edge micro-pad for emergency edits.
Strategic Finding: Maintaining two disparate CMS codebases (a custom quick-pad and an open-source studio) introduces architectural drift, duplicate data models, and double the testing burden. Unifying 100% on EmDash CMS provides a single, robust, Astro-native system that covers both quick mobile announcements and full desktop content management.

3. The Definitive Architectural Decision: Unified EmDash CMS Engine

Rather than forcing a false choice between building an entire CMS from scratch or wrestling with bloated, server-dependent platforms (Directus/Strapi/Payload), SiteSwarm formally adopts EmDash (emdash + @emdash-cms/cloudflare) as the platform’s unified open-source CMS foundation.

3.1 Why EmDash is the Platform’s Authoritative CMS:

Never Reinvent the Wheel: Building production-ready media uploaders, image cropping/optimization pipelines, typed schema builders, and administrative dashboards from scratch is high-friction, low-differentiation engineering. EmDash delivers a modern, MIT-licensed open-source engine purpose-built for our exact edge requirements.
First-Class Astro Ecosystem Alignment: Unlike Payload (which forces Next.js and OpenNext compilation) or Strapi/Directus (which demand persistent Node.js servers), EmDash is authored natively in and for Astro. It compiles cleanly into our client applications’ edge workers without multi-framework impedance mismatch.
Sandboxed Worker Isolate Plugins for Agency Upsells: EmDash executes plugins inside isolated Cloudflare V8 isolates with explicit capability permissions. This provides the exact substrate SiteSwarm needs to author and distribute high-margin upsell plugins (Google Business Profile auto-sync, SMS broadcasts via Twilio, Instagram edge cache) safely across client sites without risking core site availability.
Cloudflare Native Economics: Runs natively on Cloudflare Workers + D1 (SQLite at the edge) + R2 (zero-egress object storage). Zero VPS management, zero Linux patch cycles, and sub-$0.50/month amortized cost across the client fleet on a single Workers Paid plan ($5/mo for 10M requests).
Agent-First Architecture (Native MCP Support): EmDash includes native Model Context Protocol (MCP) capabilities at /_emdash/api/mcp, allowing Antigravity and AI coding agents to inspect schemas, execute migrations, and manage content programmatically during continuous integration.

3.2 Unified Content Delivery Model & Worker Splitting Architecture

As formalized in ADR-0003, SiteSwarm separates the public static presentation tier from the dynamic CMS editing engine into two decoupled workers:

flowchart TD
    subgraph ClientExperience["Client Experience (Mobile & Desktop)"]
        Admin["EmDash Admin Studio (/admin or /_emdash/admin)\nDesktop & Mobile Responsive Studio\nAnnouncements, Hours, Menu Catalogs, Articles, Media"]
        Visitor["Public Visitor Browser (Anonymous Customer)\nReading Menus, Hours, Directions"]
    end

    subgraph EdgeIngress["Cloudflare Edge Anycast Gateway"]
        CF_WAF["Cloudflare WAF & Security"]
        CF_Access["Cloudflare Access / Zero Trust\n(Gates /admin* & /_emdash/*)"]
    end

    subgraph WorkerFleet["SiteSwarm Decoupled Worker Fleet"]
        subgraph WorkerA["Worker A: Public Static Frontend (@siteswarm/app-*)"]
            direction TB
            Assets["Cloudflare Assets Engine (Static Prerender)"]
            EdgeRouter["Edge Router & Proxy Handler"]
            PublicPages["/, /menu, /about, /contact\n(Sub-20ms TTFB | 0 KB Client JS | Zero Session KV)"]
        end

        subgraph WorkerB["Worker B: Isolated CMS & Admin (@siteswarm/service-cms-*)"]
            direction TB
            Auth["Edge Security & Auth (Passkeys / Cookie Sessions)"]
            Validator["Strict Typed Schemas & Zod Validation"]
            Mcp["MCP Agent Endpoint (/_emdash/api/mcp)"]
            EmDashCore["EmDash Core Engine (Astro/React Studio)"]
            Storage["Cloudflare D1 Storage (Exclusive SQLite Binding)"]
            Media["Cloudflare R2 Object Storage (Images & Media)"]
        end
    end

    subgraph EdgeCache["Edge Invalidation Bridge (Epic #38)"]
        CachePurge["Cloudflare Cache-Tag Purge (<150ms Global Purge)"]
    end

    Visitor --> CF_WAF --> WorkerA
    WorkerA --> Assets --> PublicPages

    Admin --> CF_WAF --> CF_Access
    CF_Access -->|Authenticated Staff| WorkerA
    WorkerA -->|Service Binding: env.CMS_SERVICE\nPaths: /admin*, /_emdash/*| WorkerB

    WorkerB --> Auth --> Validator --> EmDashCore
    EmDashCore --> Storage
    EmDashCore --> Media
    Mcp --> Validator
    Storage --> CachePurge
    CachePurge -.->|"Invalidates Cached Slot HTML"| WorkerA

3.3 The Isolated CMS Worker Architecture (Worker Splitting & D1 Separation)

Decoupling the CMS into a dedicated edge service provides three fundamental architectural guarantees:

3.3.1 Blast Radius Isolation

Process & Memory Boundary: Worker B runs in an independent Cloudflare V8 worker isolate. Heavy administrative JavaScript libraries, React studio bundles, image optimization tasks, and database migration routines execute exclusively within Worker B.
Resilience Invariant: A fatal error, uncaught exception, or out-of-memory crash inside the CMS engine or a third-party plugin can never crash or degrade the public client website. Worker A continues serving public visitors at 100% availability from edge cache and static assets.
Independent Versioning & Deployment: Upgrades to EmDash CMS or capability plugins can deploy to Worker B without triggering recompilations or invalidating static bundles of Worker A.

3.3.2 D1 Database Binding Separation & Read Shielding

Exclusive Privileged Access: The Cloudflare D1 database binding (binding: "DB") is attached strictly to Worker B. Worker A has zero direct database credentials or bindings.
Zero SQL Injection Surface on Public Path: Because Worker A has no database binding or SQL client libraries, the public web interface cannot be exploited via SQLite injection attacks against core client tables.
Cache Stampede Prevention: Viral traffic surges (e.g. a local news feature or food critic review) are absorbed entirely by Cloudflare Anycast edge cache and Worker A’s static assets. Public visitors never query D1 directly, shielding SQLite concurrency limits and keeping database write latency low.

3.3.3 Zero-Session-KV Guarantee

Astro Prerender Mode: Worker A builds in pure static prerender mode (output: "static"). Astro’s default server session KV binding is completely omitted (SESSION binding = 0).
Ephemeral Preview Velocity: Ephemeral PR preview deployments for client frontends provision zero KV namespaces. Cloudflare account quotas are protected, and teardown workflows require zero cascading KV namespace deletions.
Isolated CMS Sessions: Any administrative session state needed for EmDash authentication is managed inside Worker B via encrypted HTTP-only cookies or an isolated administrative store, keeping the public frontend 100% stateless.

3.3.4 Service Binding Communication & Invalidation Bridge

0ms Internal Ingress: Worker A proxies incoming requests matching /admin* and /_emdash/* directly to Worker B using native Cloudflare Service Bindings (env.CMS_SERVICE.fetch(request.clone())). The request stays within the same Cloudflare data center isolate with zero network overhead.
Freshness Lifecycle (Epic #38 Alignment): When an authorized business owner commits an update in Worker B, an invalidation hook triggers a Cloudflare Cache-Tag purge for the client’s tenant tag. Global edge caches invalidate in under 150ms, achieving sub-2-second end-to-end freshness from phone to visitor.

3.4 Commercial Packaging & Support Tiers

The intent of the platform is to support various commercial service tiers (e.g. foundational operational edits vs full marketing retainers), configured through agency service agreements and EmDash permissions:

Base Client Tier (Forever Free / Zero Lockout): Included in the base application build. Clients have access to EmDash for core operational entities (emergency alerts, operating hours, daily specials, and contact information) backed by their dedicated Cloudflare D1 database.
Content & Growth Retainers (Paid Retainers): Clients unlock expanded capabilities within EmDash—including Cloudflare R2 media library uploads, multi-category catalogs, staff bios, and sandboxed Worker isolate plugins.

4. Commercial Strategy: Packaging, Pricing & The Plugin Flywheel

The CMS architecture directly mirrors SiteSwarm’s business flywheel. By providing a unified EmDash foundation out of the box, we establish unbreakable trust with local business owners. By offering modular plugins and packages, we create recurring revenue opportunities without custom development overhead.

flowchart LR
    subgraph Base["Base Deployment"]
        B1["Bespoke UI Design"]
        B2["EmDash Core CMS"]
        B3["Zero Lockout / Free Forever"]
    end

    subgraph ContentRetainer["Content Retainer ($99/mo)"]
        C1["R2 Media Library"]
        C2["Seasonal Menu / Catalog Manager"]
        C3["Staff & Testimonial Blocks"]
    end

    subgraph OperationsRetainer["Operations & Growth ($199/mo)"]
        O1["Table Booking / Inquiries"]
        O2["Catering Quote Request Routing"]
        O3["Customer Reviews Engine"]
    end

    subgraph Plugins["A La Carte Plugin Upsells ($29-$49/mo)"]
        P1["Google Business Profile Sync"]
        P2["SMS Customer Broadcast (Twilio)"]
        P3["Instagram Feed Auto-Cache"]
        P4["Automated Monthly ROI Report"]
    end

    Base --> ContentRetainer
    ContentRetainer --> OperationsRetainer
    Base -.-> Plugins
    ContentRetainer -.-> Plugins

4.1 Feature Matrix & Capability Breakdown

Feature / Capability	Base Website (Included)	Content Retainer ($99/mo)	Growth Retainer ($199/mo)	A La Carte Add-On
Emergency Announcement Banner	✅ Yes	✅ Yes	✅ Yes	—
Hours & Holiday Schedule Overrides	✅ Yes	✅ Yes	✅ Yes	—
Daily Featured Special (Text)	✅ Yes	✅ Yes	✅ Yes	—
EmDash Admin Studio Access	✅ Yes	✅ Yes	✅ Yes	—
Media Library & Image Uploads (R2)	❌ (Agency Managed)	✅ Yes (Self-Serve)	✅ Yes (Self-Serve)	$29/mo
Full Menu / Catalog Category Manager	❌ (Agency Managed)	✅ Yes (Self-Serve)	✅ Yes (Self-Serve)	$39/mo
Staff & Testimonial Manager	❌ (Agency Managed)	✅ Yes (Self-Serve)	✅ Yes (Self-Serve)	$29/mo
Event Calendar & RSVP Links	❌ (Agency Managed)	❌ (Agency Managed)	✅ Yes (Self-Serve)	$39/mo
Catering & Inbound Inquiry Builder	❌ (Agency Managed)	❌ (Agency Managed)	✅ Yes (Self-Serve)	$49/mo
Google Business Profile Auto-Sync	❌	Optional Plugin	Optional Plugin	$39/mo
SMS Customer Broadcast (Twilio)	❌	Optional Plugin	Optional Plugin	$49/mo
Instagram Edge Auto-Cache	❌	Optional Plugin	Optional Plugin	$19/mo

4.2 The Modular Plugin Architecture

Plugins are authored as self-contained capability packages in packages/plugins/ adhering to the EmDash/Worker isolate contract. Each plugin implements:

Schema Declaration: Extends the D1 schema with typed tables or JSON properties.
Admin Widget: Injects a clean mobile card into the admin UI.
Edge Hook / Cron: Performs background syncing or webhooks without blocking the main website.

Example Plugin: Google Business Profile Auto-Sync (`@siteswarm/plugin-gbp-sync`)

Trigger: When the bakery owner updates their holiday hours or emergency closure in EmDash CMS.
Execution: A background Cloudflare Worker queue event is dispatched.
Action: Uses the Google My Business API to synchronize the updated hours to Google Maps and Search immediately, preventing customers from driving to a closed shop based on outdated Google Maps listings.

Example Plugin: Emergency SMS Broadcast (`@siteswarm/plugin-sms-blast`)

Trigger: Bakery owner activates an urgent storm closure banner and checks “Notify SMS Subscribers”.
Execution: Worker queries client’s D1 opt-in phone list and dispatches a bulk SMS via Twilio edge webhook.
Value: High-margin recurring upsell for the agency with zero manual intervention.

5. The 60-Second Mobile Usability Benchmark

To guarantee that non-technical business owners can operate the tool without anxiety, the interface must strictly follow the Mobile Usability Benchmark:

+-------------------------------------------------------------+
|  🍞 GREEN LEAF BAKERY — EMDASH CMS                [Log Out] |
+-------------------------------------------------------------+
|                                                             |
|  📢 EMERGENCY ANNOUNCEMENT BANNER                           |
|  Status: [● Active]   [○ Inactive]                          |
|  Message:                                                   |
|  [ Sold out of sourdough! Fresh baguettes at 11am!       ]  |
|  Severity: [ Information ]  [(●) Urgent Notice ]            |
|                                                             |
+-------------------------------------------------------------+
|                                                             |
|  ⏰ TODAY'S OPERATING HOURS                                 |
|  Status: [ (●) Open Regular (6:30 AM – 3:00 PM)           ]  |
|          [ ( ) Closed Today / Emergency Weather           ]  |
|          [ ( ) Custom Hours Today: [08:00] to [12:00]     ]  |
|                                                             |
+-------------------------------------------------------------+
|                                                             |
|  🍲 DAILY SPECIAL                                           |
|  Title: [ Wood-Fired Roasted Peach Galette                ]  |
|  Price: [ $6.75 ]                                           |
|                                                             |
+-------------------------------------------------------------+
|                                                             |
|  =========================================================  |
|  [           🚀  PUBLISH TO LIVE WEBSITE  (Instant)      ]  |
|  =========================================================  |
|  ✓ Live site updates in < 2 seconds across all edge nodes.   |
+-------------------------------------------------------------+

5.1 Mobile Performance Budget & Interaction Flow:

Responsive Admin Studio: EmDash provides a fully mobile-optimized, responsive studio mounted at /_emdash/admin, with /admin automatically redirecting clients directly into the workspace.
Fast Edge Delivery: Rendered directly by Astro with minimal edge isolate overhead (< 500ms on cellular 4G LTE).
Authentication Persistence: Secure, HttpOnly cookie sessions. The client bookmarks mysite.com/admin to their smartphone home screen; on subsequent visits, they are already authenticated.
Total Task Completion Time:
- Step 1: Tap home screen icon / navigate to /admin (redirects to /_emdash/admin) (1–2 sec).
- Step 2: Select “Emergency Announcement” or “Operating Hours” (2 sec).
- Step 3: Type announcement message or adjust hours (15 sec).
- Step 4: Tap “Publish” button (1 sec).
- Step 5: D1 transaction completes and live site renders updated data (2 sec).
- Total Elapsed Time: ~21 seconds (Well under the 60-second limit).

6. Blast Radius, Data Integrity & Layout Safety Invariants

In a bespoke application architecture where UI templates are individually crafted for each client, client CMS inputs must never break page layout or cause accessibility failures.

flowchart TD
    subgraph InputValidation["1. Ingestion & Validation Gate"]
        In["Client Mobile Submission"] --> Zod["Strict Zod Schema Validation"]
        Zod --> Sanitizer["HTML Strip & Entity Escaping\n(Zero Raw HTML Allowed)"]
        Sanitizer --> Len["Character Length & Ratio Guards"]
    end

    subgraph AtomicStorage["2. Atomic Storage & Cache Invalidation"]
        Len --> D1["Atomic Cloudflare D1 Write\n(SQLite Transaction)"]
        D1 --> KV["Cloudflare KV Fast Cache Update\n(TTL: 60s, Purged on Write)"]
    end

    subgraph RuntimeRendering["3. Defensive Runtime Rendering (Astro)"]
        KV --> Slot["Astro Dynamic Edge Slot"]
        D1 -.->|Fallback if KV Miss| Slot
        Seed["Static Default Seed Data"] -.->|Fallback if DB Error| Slot
        Slot --> Output["100% Valid, Accessible HTML Rendered"]
    end

6.1 Defense-in-Depth Safety Rules:

Zero Raw HTML Injection: Content fields accept only plain text or strictly controlled Markdown subsets (bold, italic, links). No <script>, <iframe>, <div>, <style>, or arbitrary attributes are permitted.
Strict Layout Length Constraints:
- Announcement Banner: Maximum 140 characters (prevents layout clipping on mobile headers).
- Daily Special Title: Maximum 60 characters.
- Operating Hours Notes: Maximum 80 characters.
The Seed Fallback Invariant: If Cloudflare D1 or KV encounters an intermittent edge failure or network partition, the client’s public website never renders a 500 error or blank slot. The Astro template automatically falls back to the static seed data defined in swarm.config.ts.
Accessibility (WCAG 2.1 AA) Safeguard:
- Announcement banners render with appropriate semantic markup (role="region" and aria-live="polite").
- Color styling is locked to pre-calculated, accessible contrast tokens established in the client’s design theme. Clients select semantic intent (Info, Warning, Urgent), never hex color codes.

7. Authentication & Edge Security Architecture

Authentication for non-technical small business owners must be completely frictionless on smartphones while remaining impermeable to unauthorized access and automated brute-force attacks.

sequenceDiagram
    autonumber
    actor Client as Business Owner (Mobile/Desktop)
    participant AdminRoute as /admin (Astro Route)
    participant EmDashAdmin as /_emdash/admin (EmDash Studio)
    participant AuthEngine as EmDash Auth & Session Engine
    participant D1 as Cloudflare D1 (Auth & Content DB)

    Client->>AdminRoute: GET /admin
    AdminRoute-->>Client: 302 Redirect to /_emdash/admin
    Client->>EmDashAdmin: GET /_emdash/admin
    alt Uninitialized Setup
        EmDashAdmin-->>Client: 302 Redirect to /_emdash/admin/setup
        Client->>EmDashAdmin: Complete Admin Setup Credentials
        EmDashAdmin->>D1: Seed Initial Admin User & Cryptographic Salt
    else Authenticated Session Active
        EmDashAdmin->>AuthEngine: Verify Session Cookie
        AuthEngine->>D1: Validate Session Token
        EmDashAdmin-->>Client: 200 OK (Render Responsive Studio Dashboard)
    else No Active Session
        EmDashAdmin-->>Client: Render Login / Passkey Screen
        Client->>EmDashAdmin: Submit Credentials / WebAuthn Passkey
        EmDashAdmin->>D1: Verify Credentials
        EmDashAdmin-->>Client: Set HttpOnly, Secure, SameSite=Strict Session Cookie
    end

7.1 Security & Access Guardrails:

Cloudflare Edge Protection: All administrative endpoints are edge-evaluated by Cloudflare Workers and can be layered behind Cloudflare Access or Turnstile for enterprise zero-trust security.
Setup Lockout Invariant: The initial administrative setup route (/_emdash/admin/setup) is immediately locked out upon creation of the primary admin user account.
Session Token Hardening:
- Session tokens are stored in HttpOnly, Secure, SameSite=Strict cookies.
- Database sessions are tied to Cloudflare D1 with automatic expiration and revocation support.
Rate Limiting & Abuse Prevention:
- Authentication requests are rate-limited via Cloudflare Worker bindings to prevent brute-force attacks.

8. Cloudflare Workers Paid Plan Justification & Fleet Economics

A central question in the technical evaluation was whether SiteSwarm requires the Cloudflare Workers Paid plan, and how that impacts fleet economics.

8.1 The Cost Comparison: Workers Paid vs. Dedicated Servers

Operational Model	Infrastructure Components	Monthly Cost (10 Clients)	Monthly Cost (50 Clients)	Maintenance Overhead
Traditional CMS (Strapi / Directus)	10–50 VPS Containers (Render/Fly/DO) + Postgres instances	$100 – $250 / month	$500 – $1,250 / month	🔴 10–15 hours/month patching OS, Docker, database tuning
Edge Fleet (Cloudflare Workers Free)	Cloudflare Pages + Workers Free (3MB limit) + D1	$0.00 / month	$0.00 / month	🟢 Zero server maintenance; limited to 3MB script bundles
Edge Fleet (Cloudflare Workers Paid)	Cloudflare Account-Level Workers Paid (10MB limit) + D1 + R2	$5.00 / month flat	$5.00 / month flat	🟢 Zero server maintenance; unlocks 10MB bundles & R2 storage

8.2 Architectural Assessment:

The $5/Month Account-Level Advantage: Cloudflare Workers Paid costs $5/month per account, NOT per website. It includes 10 million requests/month, allows script bundles up to 10 MB, and provides expanded CPU execution limits.
Amortized Fleet Cost:
- With 10 clients on the roster, hosting cost is $0.50 per client per month.
- With 50 clients on the roster, hosting cost drops to $0.10 per client per month.
Strategic Conclusion: The $5/month Workers Paid tier is completely aligned with our near-$0 operating thesis. It delivers 100x the reliability of dedicated virtual machines at less than 5% of the financial and maintenance cost.

9. Implementation Roadmap & Sub-Ticket Decomposition

To transition this specification into production execution across Horizons 1 and 2, the following shovel-ready engineering sub-tickets are defined:

flowchart TD
    T1["Sub-Ticket 1: EmDash Astro Core Integration\n(emdash/astro + @emdash-cms/cloudflare + D1 Binding)"] --> T2["Sub-Ticket 2: Client App Admin Route & Redirect\n(/admin -> /_emdash/admin redirect + setup gate)"]
    T2 --> T3["Sub-Ticket 3: Dynamic Edge Slots & Seed Fallback\n(Astro edge components + D1 query integration)"]
    T3 --> T4["Sub-Ticket 4: Modular Plugin Architecture\n(Worker isolate plugins for GBP sync, SMS, R2 media)"]

9.1 Shovel-Ready Sub-Tickets:

feat(cms): integrate EmDash CMS engine with Cloudflare D1 binding:
- Install emdash, @emdash-cms/cloudflare, and @astrojs/react.
- Configure astro.config.mjs with emdash({ database: d1({ binding: "DB" }) }).
- Resolve Vite SSR chunking for Kysely to guarantee zero runtime circular evaluation issues.
feat(cms): author /admin redirect and unified admin access:
- Implement clean 302 redirect from /admin to /_emdash/admin.
- Verify EmDash health check (/_emdash/api/health) and OpenAPI manifest endpoints.
feat(app): wire client dynamic edge slots with static seed fallback:
- Connect client app templates (emergency alert banner, operating hours, specials, menu catalog) to live D1 storage.
- Enforce zero-lockout offline fallback invariant when running disconnected or during cold starts.
feat(plugins): implement commercial retainer plugins & R2 media connector:
- Establish plugin contract for agency upsell retainers (Google Business Profile auto-sync, SMS broadcast, R2 media library).

10. Conclusion & Specification Status

By establishing EmDash CMS as the unified client content management engine across the SiteSwarm fleet, the platform achieves the optimal balance:

Small business owners gain the freedom to update their business from their phone or desktop in seconds without depending on an agency.
Daytime engineers eliminate daytime support interruptions while maintaining a zero-maintenance, serverless architecture.
The business model unlocks profitable, high-margin monthly retainers and plugin upsells without maintaining divergent codebases or ballooning infrastructure overhead.

This document represents the canonical, authoritative ground truth for all CMS implementations across the SiteSwarm fleet.

Client Content Management (CMS) & Mobile BAU Editing True Specification

Client Content Management (CMS) & Mobile BAU Editing True Specification

1. Executive Summary & The Core Architectural Invariant

The Three Foundational CMS Invariants:

2. Contender Evaluation & Technical Audit Matrix

2.1 Comprehensive Contender Matrix

2.2 Deep-Dive Contender Audits

2.2.1 Contender 1: Strapi (Investigated on Cloudflare Workers)

2.2.2 Contender 2: Directus

2.2.3 Contender 3: Payload CMS v3 on Cloudflare Workers

2.2.4 Contender 4: Git-Backed Headless CMS (Decap CMS, TinaCMS, Keystatic)

2.2.5 Contender 5: EmDash CMS (Cloudflare + Astro + D1 + R2)

2.2.6 Evaluation Summary & Resolution

3. The Definitive Architectural Decision: Unified EmDash CMS Engine

3.1 Why EmDash is the Platform’s Authoritative CMS:

3.2 Unified Content Delivery Model & Worker Splitting Architecture

3.3 The Isolated CMS Worker Architecture (Worker Splitting & D1 Separation)

3.3.1 Blast Radius Isolation

3.3.2 D1 Database Binding Separation & Read Shielding

3.3.3 Zero-Session-KV Guarantee

3.3.4 Service Binding Communication & Invalidation Bridge

3.4 Commercial Packaging & Support Tiers

4. Commercial Strategy: Packaging, Pricing & The Plugin Flywheel

4.1 Feature Matrix & Capability Breakdown

4.2 The Modular Plugin Architecture

Example Plugin: Google Business Profile Auto-Sync (@siteswarm/plugin-gbp-sync)

Example Plugin: Emergency SMS Broadcast (@siteswarm/plugin-sms-blast)

5. The 60-Second Mobile Usability Benchmark

5.1 Mobile Performance Budget & Interaction Flow:

6. Blast Radius, Data Integrity & Layout Safety Invariants

6.1 Defense-in-Depth Safety Rules:

7. Authentication & Edge Security Architecture

7.1 Security & Access Guardrails:

8. Cloudflare Workers Paid Plan Justification & Fleet Economics

8.1 The Cost Comparison: Workers Paid vs. Dedicated Servers

8.2 Architectural Assessment:

9. Implementation Roadmap & Sub-Ticket Decomposition

9.1 Shovel-Ready Sub-Tickets:

10. Conclusion & Specification Status

Example Plugin: Google Business Profile Auto-Sync (`@siteswarm/plugin-gbp-sync`)

Example Plugin: Emergency SMS Broadcast (`@siteswarm/plugin-sms-blast`)