SiteSwarm — High-Level Design (HLD)

SiteSwarm — High-Level Design (HLD)

Document Status: Draft / Architectural Foundation
Target Audience: Core Engineering & Architecture Contributors
Related Documents: docs/PRD.md, README.md, docs/CAPABILITY_MANAGEMENT.md, docs/INGRESS_AND_PREVIEW_ROUTING.md, docs/CLIENT_CMS.md, docs/DATA_ISOLATION_AND_STORAGE.md, ADR-0003
Philosophy: Get the full picture before choosing the colors. Detailed framework, storage, and ingress specifics are intentionally deferred to future Living True Specifications.

---

1. Executive Summary & Architectural Goals

SiteSwarm is an agent-first software engineering backbone engineered to deliver personalized, feature-rich web applications for local small businesses while minimizing ongoing management overhead.

As software engineers maintaining full-time daytime careers, our development time is concentrated in off-hours. To scale a roster of client businesses without being overwhelmed by maintenance, SiteSwarm is designed around four foundational architectural pillars:

flowchart TD
    subgraph CorePillars["The Four Architectural Pillars"]
        direction TB
        P1["1. Independence at Runtime\nEach client app deploys and runs as an autonomous, isolated service."]
        P2["2. Unity at Build Time\nA monolithic repository distributes CI, linters, accessibility, and shared capability packages."]
        P3["3. Agent-First Velocity\nAI coding agents handle scaffolding, boilerplate, and repetitive adaptations."]
        P4["4. Proactive Edge Observability\nAutomated alarms and synthetic health checks surface issues before clients notice."]
    end

Key Architectural Metrics:

• Marginal Maintenance Overhead: Adding the $N$-th client application should incur near-zero additional daily operational burden.
• Cross-Fleet Tooling Leverage: Any improvement in accessibility, security headers, performance, or SEO created for Client A immediately benefits Clients B through Z.
• Scaffolding Velocity: Spinning up a brand-new, customized client application with full CI/CD, styling contracts, and monitoring takes minutes, not weeks.

---

2. System Topology: The Monolithic Backbone

The system uses a monolithic repository architecture with decoupled production runtimes. This gives us the velocity and shared tooling of a monorepo without coupling our clients’ availability or infrastructure.

flowchart TD
    subgraph Repo["SiteSwarm Monolithic Repository"]
        subgraph Apps["apps/ (Independent Client Frontends)"]
            App1["Client A App (e.g. Local Bakery)"]
            App2["Client B App (e.g. Auto Repair)"]
            App3["Client C App (e.g. Dental Clinic)"]
        end

        subgraph Shared["packages/ (Shared Tooling & Contracts)"]
            T1["Shared CI / Test Workflows"]
            T2["Code Quality & Linters"]
            T3["Accessibility (a11y) Engine"]
            T4["Capability Catalog & Contracts"]
            T5["Synthetic Alarms & Monitoring"]
        end

        T1 & T2 & T3 & T4 & T5 -.-> App1 & App2 & App3
    end

    subgraph Cloud["Modern Cloud Platform (Cloudflare Edge Fleet)"]
        subgraph ClientADeploy["Client A Deployment"]
            WorkerA1["Worker A: Public Static Frontend\n(Sub-20ms TTFB, 0 KB JS, Zero Session KV)"]
            WorkerB1["Worker B: Isolated CMS & Admin\n(EmDash Studio, D1 Database)"]
            WorkerA1 -->|0ms Service Binding: /admin*| WorkerB1
        end
        subgraph ClientBDeploy["Client B Deployment"]
            WorkerA2["Worker A: Public Frontend"]
            WorkerB2["Worker B: CMS Worker"]
            WorkerA2 -->|0ms Service Binding| WorkerB2
        end
    end

    App1 --> ClientADeploy
    App2 --> ClientBDeploy

2.1 Why Monolithic at Build Time?

• Unified Standards: Linters, formatting, TypeScript configurations, and dependency updates are handled in one place.
• Zero Drift: When an accessibility audit rule or security header best practice is updated, all client applications automatically inherit the verification on their next build.
• Tooling Consolidation: Developers and AI agents operate within a consistent, uniform structure regardless of which client application they are actively developing.

2.2 Why Independent at Runtime?

• Blast Radius Containment: A spike in traffic or an application-level bug in Client A’s application never degrades or affects Client B or C.
• Independent Release Cadence: Updating Client A’s menu or business hours requires building and deploying only Client A’s service—zero downtime or risk for other clients.
• Client Portability: If a client ever leaves or requires self-hosting, their isolated application package can be cleanly extracted.

2.3 Decoupled Client Edge Runtime: Worker Splitting & Zero-Session-KV

As formalized in ADR-0003, each client web application is partitioned into two physically decoupled workers at runtime:

1. Worker A (Public Static Frontend):
   • Static-First Delivery: Built in pure static prerender mode (output: "static" via Cloudflare Assets). Delivers 0 KB client JavaScript for content pages and guarantees sub-20ms edge TTFB globally.
   • Zero-Session-KV Guarantee: Small business client websites are content-driven and do not require visitor sessions. Astro’s default session KV binding is omitted (SESSION = 0), preventing ephemeral KV namespace sprawl during PR preview deployments and eliminating account quota limits.
   • Shielded Storage Path: Has zero direct bindings to Cloudflare D1 or R2, eliminating SQL injection attack surfaces and protecting the database from viral traffic spikes.
2. Worker B (Isolated CMS & Admin Worker):
   • Dedicated Administration: Runs the EmDash CMS administrative studio, dynamic APIs (/_emdash/*, /admin), passkey/magic-link authentication, and Model Context Protocol (MCP) agent endpoints.
   • Exclusive Database Ownership: Holds the privileged Cloudflare D1 SQLite database binding (DB) and R2 media bucket binding (MEDIA).
   • Security Perimeter: Shielded behind Cloudflare Zero Trust / Cloudflare Access policies without impacting anonymous public visitors.
   • Zero-Latency Ingress via Service Bindings: Worker A proxies incoming requests to /admin* and /_emdash/* directly to Worker B at 0ms in-process latency using native Cloudflare Service Bindings (env.CMS_SERVICE.fetch()).

2.4 Domain-Oriented Multi-Worker Platform Services Topology

As specified in MULTI_WORKER_PLATFORM_SERVICES.md (Companion Epics: #34, #35, and #101), SiteSwarm rejects a monolithic “god worker” for shared backend functionality. Instead, cross-cutting horizontal capabilities run as dedicated, isolated platform services:

• services/leads-service: Antispam honeypot evaluation, Cloudflare Turnstile token verification, rate limiting, and webhook/SMS/email delivery.
• services/cms-service: Multi-tenant D1/KV storage engine, emergency alert banners, and static fallback seeds.
• services/synthetic-monitoring: Scheduled cron probes, edge uptime aggregation, and PagerDuty/webhook dispatch.
• services/analytics-service: Privacy-preserving, zero-cookie edge pageview telemetry.

All client applications communicate with platform workers via zero-latency Cloudflare Service Bindings (env.LEADS_SERVICE, env.CMS_SERVICE) with mandatory tenant context injection (tenantId = manifest.appId), ensuring zero public HTTP overhead and complete credential isolation.

---

3. The Swarm Tooling Distribution Flywheel

In a traditional agency, codebases fork and diverge. In SiteSwarm, every client is part of a continuous improvement flywheel:

sequenceDiagram
    autonumber
    actor Dev as Developer / AI Agent
    participant Shared as Shared Swarm Backbone
    participant ClientA as Client A Application
    participant ClientB as Client B Application
    participant CI as Swarm CI Pipeline

    Dev->>ClientA: Build bespoke feature / Solve accessibility issue
    Dev->>Shared: Extract generalizable linter rule, headless package, or alarm
    Shared->>CI: Run shared verification across affected apps
    CI-->>ClientA: Verified & Deployed
    CI-->>ClientB: Inherits enhancement, shared libraries & protection against regressions

3.1 Shared Workflows & Quality Gates

• Continuous Integration: Centralized CI workflows execute linting, typechecking, and tests across all applications, using incremental change detection so only modified applications and their dependencies are evaluated.
• Accessibility (a11y) & Performance Auditing: Automated checks (contrast ratios, semantic HTML, screen reader labels, core web vitals budgets) run uniformly against every client app.
• Code Quality & Style Linters: Consistent code standards across all client apps ensure any developer or agent can jump into any project instantly without learning unique conventions.

3.2 Bespoke Visual UI Freedom & Shared Code Libraries

A traditional agency challenge is balancing code reuse against visual variety. Traditional agency frameworks often attempt to solve this by forcing all client applications through a centralized visual component library and theme adapter (e.g., swapping CSS variables on a shared button, card, or navigation bar).

SiteSwarm draws a clear architectural distinction between visual presentation and shared code libraries:

flowchart TD
    subgraph TraditionalAntiPattern["Traditional Visual Component Reuse (Avoided)"]
        TC1["Monolithic Shared UI Components\n(Buttons, Navbars, Cards)"] --> TC2["Theme Adapters & CSS Token Overrides"]
        TC2 --> TC3["Visual Monotony ('All sites look identical')\n& Tight Coupling (Changes break other clients)"]
    end

    subgraph SiteSwarmModel["SiteSwarm Model: Bespoke Visuals + Shared Headless Libraries"]
        direction TB
        S1["Shared Code Libraries in packages/*\nHeadless capabilities, validation, types, unstyled primitives"]
        S2["AI Agent Generates 100% Bespoke Visual UI\nIndependent HTML/CSS/Astro per client in apps/<client>/"]
        S3["Automated CI Quality Gatekeepers\nRuthless evaluation: WCAG 2.1 AA, Lighthouse >= 95, Edge compliance"]
        S1 --> S2
        S2 --> S3
    end

1. Why Bespoke Visual UI is Free with AI

• Eliminating Artificial Constraints: When developers are forced to fit a local bakery, a dental clinic, and an auto mechanic into the same shared visual component hierarchy, the results feel generic and cookie-cutter. Overriding styles requires fragile CSS hacks and complex specificity overrides.
• Blast Radius & Coupling Containment: In a shared visual UI library, tweaking padding or font sizing for Client A’s navbar risks unexpected visual regressions in Client B or Client C.
• Zero-Cost Generation: Generating tailored semantic HTML, responsive CSS, and Astro layouts is instantaneous with AI coding agents. Each client application under apps/<client>/ possesses its own independent visual presentation completely free from shared UI component inheritance.

2. The Power of Shared Code Libraries

Rejecting rigid visual UI adapters does not mean avoiding shared code. On the contrary, SiteSwarm’s shared monolithic backbone (packages/*) provides immense leverage across the fleet:

• Headless Capability Packages (@siteswarm/*): Complex, stateful, or integration-heavy features (Turnstile-protected lead capture, booking workflows, inventory synchronization, dynamic SEO metadata) are packaged as headless modules. Client apps compose these capabilities directly with their unique visual UI.
• Unstyled Primitives & Utilities: Shared headless accessibility primitives (keyboard-trap managers, focus routers, dialog behaviors), date formatters, and telephone formatters eliminate boilerplate without dictating styling.
• Type Contracts & Governance (@siteswarm/governance): Shared TypeScript schemas ensure all apps declare capabilities, environment variables, and target paths in a uniform, compile-time verified manner.

3. Automated Evaluation Gates as the Quality Firewall

Because visual code is authored rapidly and bespoke for each client, shared tooling’s primary responsibility shifts from providing visual UI to acting as an unforgiving automated quality gatekeeper in CI:

• WCAG 2.1 AA Accessibility: Hard CI gate requiring zero automated accessibility violations.
• Mobile Performance Budget: Lighthouse mobile score $\ge 95$, initial JavaScript payload $< 50$ KB, and strict cumulative layout shift budgets.
• Edge Runtime Compatibility: Static analysis ensuring zero unsupported Node.js runtime APIs in Cloudflare Worker/Pages bundles.
• Semantic HTML & Schema.org: Automated validation of heading hierarchies and LocalBusiness JSON-LD structured data.

---

4. Client Onboarding: Technical Scaffolding vs. UI Templates

A critical architectural distinction in SiteSwarm is how new client applications are birthed:

We do not provide rigid UI “templates” (e.g., “Restaurant Theme A vs. Salon Theme B”). Instead, we provide technical scaffolding that plugs into reusable swarm packages.

flowchart TD
    subgraph AntiPattern["Rigid UI Template (Avoided)"]
        T1["Pre-baked Layout & Styles"] --> T2["Hard to Customize"]
        T2 --> T3["Bloated Overrides & CSS Hacks"]
        T3 --> T4["Clients Feel Cookie-Cutter"]
    end

    subgraph SiteSwarmPattern["SiteSwarm Technical Scaffolding (Adopted)"]
        S1["Clean Standalone App Scaffold"]
        S2["Standard Wiring: Routing, Types, Build Configs"]
        S3["Plugs into Shared Packages: Capabilities, Headless Logic, Types, Alarms"]
        S4["Bespoke Visual UI: 100% Tailored to Client Brand & Verified by CI Gates"]
        S1 --> S2 --> S3 --> S4
    end

4.1 Retaining Standalone Flexibility with Scaffolding Velocity

• The Pluggable Skeleton: Scaffolding provides all foundational plumbing—TypeScript definitions, build and edge deployment scripts, routing structures, and manifest contracts.
• Shared Package Composition: New apps instantly import and wire into shared capability packages (@siteswarm/*), telemetry runners, and utility libraries without reinventing backend integration logic.
• Bespoke UI Freedom: The actual page layouts, visual hierarchy, styling, and animations remain 100% bespoke and unconstrained. A client never looks like a generic template.
• Rapid Generation: Developers and AI agents can instantiate a new, fully wired client project in minutes using scaffolding blueprints, jumping immediately to bespoke styling and feature delivery.

---

5. Stack Governance & The Capability Catalog

As the swarm expands from 3 to 10, 20, or 50 clients, management overhead could spiral if changes are not tracked systematically. Governance across the stack is the key to enabling AI agents and developers to build and evolve features smoothly.

5.1 Horizontal Platform Capabilities vs. Vertical Customizations

We categorize all application code into two distinct dimensions:

flowchart LR
    subgraph Horizontal["Horizontal Platform Capabilities (The Swarm)"]
        direction TB
        H1["Lead Capture & Turnstile Validation"]
        H2["Booking & Scheduling Engine"]
        H3["Menu / Product Catalog"]
        H4["Dynamic OpenGraph & SEO Engine"]
        H5["Proactive Synthetic Alarms"]
    end

    subgraph Vertical["Vertical Customizations (Client-Specific)"]
        direction TB
        V1["Bakery: Custom Legacy POS Sync"]
        V2["Mechanic: Bespoke VIN Lookup Form"]
        V3["Clinic: Specialized Intake Questionnaire"]
    end

    Horizontal -.->|"Adopted by contract"| ClientApp["Client Application"]
    Vertical -->|"Bespoke code"| ClientApp

1. Horizontal Capabilities: Standardized, reusable platform modules built to solve common small business needs across the fleet (e.g., lead capture with spam protection, booking calendars, dynamic SEO, menu catalogs).
2. Vertical Customizations: One-off, client-specific business logic written specifically for a single client’s unique workflow (e.g., syncing with a bespoke legacy POS system, unique pricing calculator).

5.2 The Capability Catalog & Type-Safe App Manifest (swarm.config.ts)

Every horizontal capability is registered in a central Capability Catalog. Each client application maintains a strongly typed App Governance Manifest written in TypeScript (swarm.config.ts):

apps/green-leaf-bakery/swarm.config.ts

import { defineAppConfig } from "@siteswarm/governance";

export default defineAppConfig({
  appId: "green-leaf-bakery",
  name: "Green Leaf Bakery",
  capabilities: {
    // Strongly typed horizontal platform capabilities from the Swarm catalog
    "lead-capture": {
      type: "horizontal",
      version: "1.2.0",
      targets: ["src/components/ContactSection.astro"],
      options: {
        provider: "turnstile",
        notifyChannel: "sms",
      },
    },
    "menu-catalog": {
      type: "horizontal",
      version: "2.1.0",
      targets: ["src/pages/menu.astro"],
    },
    // Explicitly tagged vertical customization
    "pos-sync-webhook": {
      type: "vertical-custom",
      description: "Bespoke webhook syncing catering orders to legacy Square terminal",
      targets: ["src/pages/api/pos-webhook.ts"],
    },
  },
});

Why TypeScript Instead of JSON?

• Zero-Drift Type Safety: Capability names, version contracts, and configuration options are validated by the TypeScript compiler (tsc). Typos or deprecated options fail builds immediately instead of silently causing runtime issues.
• Agent Self-Correction: When an AI agent modifies swarm.config.ts, TypeScript compiler diagnostics act as an immediate verification gate. If an agent hallucinates a capability or invalid parameter, the compiler catches it before a commit is ever staged.
• IDE Autocomplete & Discovery: Developers and agents receive instant IntelliSense discovering available capabilities and required target definitions.

[!TIP] For the comprehensive specification of TypeScript types, schema validator, and agent operating protocols, see the living True Specification: Capability Management & Type-Safe Governance Spec.

5.3 Agent-First Governance Ergonomics

Why does this governance matter? Because it gives AI agents a machine-readable roadmap:

• Safe Feature Backporting: When an agent is asked to “upgrade the lead capture capability across all clients,” it inspects the governance manifest of each client. It knows exactly which files consume the capability and will not break client-specific vertical code.
• Preventing Unintended One-Offs: When prompted to add a feature (e.g. appointment scheduling), an agent first checks the Capability Catalog. If a horizontal capability exists, the agent adopts the platform standard instead of authoring an unmaintained one-off vertical.
• Fleet Auditing: At any time, a developer can run a governance audit to see: “Which clients are using outdated capabilities? Where have we built one-off verticals that should be abstracted into horizontal platform features?”

---

6. Multi-App CI/CD Fleet Scaling & Environments

In a monorepo housing dozens of client websites, CI/CD cannot treat the repository as a single monolithic deployable. The deployment pipeline must scale gracefully with the fleet.

flowchart TD
    subgraph Triggers["Git Lifecycle"]
        PR["Pull Request Opened / Updated (apps/client-a/**)"]
        MergeStaging["Merge to staging"]
        MergeProd["Promotion to production"]
    end

    subgraph Pipelines["Path-Filtered CI Pipeline"]
        PR --> Det["Path & Dependency Detection\n(Evaluate affected app only)"]
        Det --> Ephemeral["Deploy Ephemeral PR Environment\nhttps://pr-42-client-a.preview.siteswarm.dev"]
        Ephemeral --> Smoke["Run Automated Edge & a11y Smoke Tests"]
        Smoke --> LiveReview["Stakeholder Live Review on Real Devices"]

        MergeStaging --> Staging["Deploy to Staging Environment\nhttps://staging-client-a.siteswarm.dev"]
        MergeProd --> Prod["Deploy to Production Environment\nhttps://client-a.com"]
    end

6.1 Ephemeral PR Preview Environments per App

• Isolated Per Pull Request: Every pull request affecting a client app automatically provisions a dedicated, ephemeral edge preview URL (e.g., https://pr-<PR_ID>-<app-slug>.preview.siteswarm.dev or https://<app-name>-preview-pr-${PR_NUM}.siteswarm.workers.dev).
• Dynamic Worker Naming & Change Detection: Preview workers are named deterministically (<app-name>-preview-pr-${PR_NUM}) and deployed strictly for impacted applications identified by the monorepo change detection engine (#53, #55). Documentation-only PRs bypass edge deployments via a 20-second fast pass.
• Graceful Zero-Secrets Fallback: Open-source forks and uncredentialed local branches execute static build and verification suites without failing CI when Cloudflare API secrets are unconfigured.
• Mobile Verification with QR Codes: Pinned PR comments provide direct preview URLs, automated edge health probe status (/_emdash/api/health or /api/health), and scannable QR codes for immediate smartphone verification by clients and stakeholders.
• Automated Ephemeral Teardown: Upon PR merge or closure, the cleanup lifecycle workflow (#56) executes wrangler delete --force to decommission edge workers and update the pinned comment, eliminating orphaned resources.

6.2 Production Ingress via Cloudflare for SaaS

• Zero Nameserver Migration: Small business clients retain their authoritative registrar and existing email MX records. Production traffic routes via standard CNAME records pointing to the SiteSwarm fallback origin (fallback.siteswarm.dev).
• Automated SSL Lifecycle: Domain Control Validation (DCV) and TLS certificate generation are handled automatically via Cloudflare for SaaS API endpoints, with zero-touch 30-day renewal.
• Apex & Subdomain Onboarding: Canonical traffic routes to www.client.com with registrar-level 301 forwarding or ALIAS/ANAME flattening for apex domains.

6.3 Staging & Production Segregation

• Path-Filtered Execution: If code changes in apps/bakery/, CI triggers builds and tests only for bakery (and any shared packages it depends on). The remaining client apps are untouched.
• Independent Staging: Each application has an active staging environment for end-to-end integration assertions.
• Gated Production Deployment: Production deployments are independent, zero-downtime atomic edge promotions. A failure in one client’s deployment never blocks or impacts another client.

[!TIP] For the comprehensive specification of Cloudflare for SaaS custom hostnames, registrar DNS onboarding runbooks, ephemeral PR preview pipelines, edge security headers, and health probing, see the living True Specification: Custom Domain Ingress, SSL Lifecycle & Ephemeral Preview Routing Spec.

---

7. Agent-First Engineering Operating Model

SiteSwarm is structured so that AI agents are first-class contributors to the development lifecycle, multiplying the productivity of engineers working off-hours:

flowchart LR
    subgraph Human["Developer (Evening / Off-Hours)"]
        H1[Community Relationship & Pitch]
        H2[Brand Ingestion & Feature Scope]
        H3[Architectural Review & Merge Gate]
    end

    subgraph Agent["AI Agent Fleet"]
        A1[Scaffold Client App from Swarm Blueprint]
        A2[Implement Custom Pages & Business Logic]
        A3[Run Automated Accessibility & Quality Verifications]
    end

    subgraph Production["Client Delivery"]
        P1[Verified Production Deployment]
    end

    H1 --> H2 --> A1 --> A2 --> A3 --> H3 --> P1

7.1 How Agents Operate in SiteSwarm

1. Blueprint Scaffolding: Rather than manually configuring directories, configs, and boilerplate, an agent uses standardized swarm blueprints to instantiate a new client application skeleton in moments.
2. Context-Confined Execution: Agents work within isolated development branches and worktrees, implementing requested client features and generating assets without polluting the main branch or touching other clients’ code.
3. Manifest Introspection: Before writing code, agents inspect the client’s swarm.config.ts (with full TypeScript compiler safety) to verify which platform capabilities are active, avoiding accidental regressions or duplicate implementations.
4. Automated Verification: Before human review, agents run the monorepo’s shared test suite, linters, and accessibility checks, correcting errors autonomously.
5. Human Review Gate: The human developer acts as the quality reviewer and relationship lead, verifying the agent’s output and approving deployments.

---

8. Operations, Observability & Low-Overhead Maintenance

To allow developers to focus on their day jobs without anxiety, operations must be proactive, self-healing, and low-touch:

flowchart TD
    subgraph EdgePlatform["Cloud Platform (e.g. Cloudflare)"]
        Edge[Edge Deployment / Static Assets / Serverless Functions]
    end

    subgraph Observability["Proactive Observability Layer"]
        Probe[Synthetic Health Probes]
        EdgeLogs[Edge Error & Latency Telemetry]
        AlertRouter[Automated Alert Router]
    end

    subgraph Notification["Instant Developer Alerts"]
        Discord[Discord / Slack / Push Webhook]
    end

    Edge --> EdgeLogs
    Probe --> Edge
    EdgeLogs & Probe --> AlertRouter
    AlertRouter --> Discord

8.1 Generously Priced Cloud Platform Economics

• Utilizing cloud platforms with generous free/low-cost tiers (such as Cloudflare) ensures that hosting costs remain near $0/month per small business client during their initial lifecycle.
• Serverless and edge-native architectures eliminate server patching, OS upgrades, and container runtime crashes.

8.2 Automated Synthetic Alarms & Probes

• Synthetic probes routinely execute HTTP health checks and critical path checks across all client domains.
• If response times degrade, certificates approach expiration, or error rates spike, alerts are dispatched immediately via webhook notifications.
• The engineering team is notified of problems before the client or their customers ever experience an outage.

---

9. Living Specifications Roadmap (“True Spec” Architecture)

Rather than generating dozens of numbered, fragmented architectural decision records that drift or conflict over time, SiteSwarm maintains a clean directory of Living True Specifications.

The True Spec Invariant: Each architectural domain has a single canonical specification document. When architectural requirements evolve or conflicting designs emerge, the True Spec is updated directly in-place so it always represents the ground-truth state of the platform.

Domain	True Specification Document	Scope & Focus	Status
Product Requirements	docs/PRD.md	Authoritative product requirements, target personas, business flywheel mechanics, and evaluation gate requirements.	🟢 Active True Spec
Capability Governance	docs/CAPABILITY_MANAGEMENT.md	TypeScript contracts (AppConfig, CapabilityDefinition), defineAppConfig helper, horizontal vs. vertical tagging, and static audit tooling.	🟢 Active True Spec
Client Content Admin (CMS)	docs/CLIENT_CMS.md	Official EmDash recommendation (Astro + Workers + D1 + R2), unified client content engine, zero-lockout mandate, and plugin flywheel.	🟢 Active True Spec
Data Isolation & Storage Strategy	docs/DATA_ISOLATION_AND_STORAGE.md	Capability-oriented multi-tier storage (platform-shared vs. dedicated D1), monorepo microservices via Service Bindings, zero data loss, and client offboarding runbook.	🟢 Active True Spec
Automated Evaluation & Linter Suite	docs/specs/EVALUATION_AND_LINTER_SUITE.md	Concrete tooling choices (axe-core, pa11y, Lighthouse CI) and threshold enforcement.	Upcoming True Spec (#22)
Capability Lifecycle & Upsell Protocol	docs/specs/CAPABILITY_LIFECYCLE_AND_UPSELL.md	Vertical feature graduation, headless package extraction, and fleet backporting protocols.	Upcoming True Spec (#23)
Domain Ingress & Ephemeral Previews	docs/INGRESS_AND_PREVIEW_ROUTING.md	Cloudflare for SaaS custom hostnames, CNAME validation, dynamic SSL, and PR preview routing.	🟢 Active True Spec
Worker Splitting & KV Elimination	docs/adr/ADR-0003-WORKER-SPLITTING-AND-KV-ELIMINATION.md	Client static edge delivery isolation from dynamic CMS worker, zero-session-KV guarantee, and 0ms Service Bindings.	🟢 Approved ADR
Digital Asset Ingestion & Optimization	docs/CLIENT_INTAKE_AND_ASSETS.md	Client asset upload intake, storage boundaries, and automated image format/resizing pipeline.	Upcoming True Spec
Client Retention & Value Reporting	docs/CLIENT_RETENTION_AND_REPORTING.md	Automated edge telemetry aggregation, ROI metrics compilation, and monthly client email dispatch.	Upcoming True Spec

---

10. Conclusion

By separating runtime isolation from build-time leverage, SiteSwarm establishes a sustainable engine for full-time engineers to build, deliver, and maintain customized, high-quality web applications for local communities at high velocity and minimal overhead.