ADR-0004: Central Command Center Architecture

Status: 🟢 Approved & Adopted
Date: 2026-10-11
Deciders: SiteSwarm Architecture Council, Platform Engineering
Related Epics & Issues: Issue #340 (Central Command Center ADR), Epic #18 (Observability, Telemetry & On-Call Alerting), Issue #276 (Fleet Monitoring & Observability Spike), Issue #28 (Client CMS), Issue #65 / ADR-0003 (Worker Splitting), Issue #101 / #324 (Multi-Worker Platform Services), Epic #31 (Client Retention & Telemetry)
Related Architecture Specifications: HIGH_LEVEL_DESIGN.md, docs/specs/MULTI_WORKER_PLATFORM_SERVICES.md, docs/CLIENT_CMS.md, docs/adr/ADR-0003-WORKER-SPLITTING-AND-KV-ELIMINATION.md, docs/DATA_ISOLATION_AND_STORAGE.md, docs/PRD.md

1. Context & Problem Statement

SiteSwarm powers a rapidly expanding fleet of bespoke client web applications for local small businesses (bakeries, auto repair shops, boutique consultancies, medical clinics). Under our Dual-Engine Operating Model, engineers maintain demanding daytime software engineering careers while scaling an agency during off-hours. This model depends on zero operational anxiety during business hours: automated guardrails must monitor client applications, ingest telemetry, and allow clients to manage business-as-usual content without engineer intervention.

However, as the fleet scales from 3 to 20 to 50+ clients, the absence of an integrated internal control plane introduces critical operational friction across four key dimensions:

1.1 The Fragmented Multi-Tenant CMS Problem

Under ADR-0003 and docs/CLIENT_CMS.md, each client application deploys an isolated administrative worker isolate (Worker B: @siteswarm/service-cms-*). While this guarantees ironclad blast radius containment and zero public frontend downtime, SiteSwarm agency staff must log in to dozens of individual domains (greenleafbakery.com/admin, apexautorepair.com/admin, etc.) to review content schemas, perform emergency text overrides, or triage media assets. Staff lack a single administrative workspace to inspect and manage dynamic client content across the entire fleet.

1.2 The Fragmented Observability & Health Visibility Problem

Fleet health is currently distributed across disparate layers: standardized edge health endpoints (/api/health via @siteswarm/health), scheduled Cloudflare Worker synthetic pinger crons (services/synthetic-monitoring), Cloudflare Tail Workers for edge error logging, and external webhooks. When an anomaly occurs, engineers must manually cross-reference raw Cloudflare dashboard logs, GitHub commit SHAs, and webhook payloads to identify the impacted client.

1.3 The Disconnected Incident & On-Call Triage Flow

Active platform incidents (e.g. D1 database connectivity degradation, edge SSL renewal delays, or elevated 5xx error spikes) trigger alerts across Discord, Slack, and BetterStack. However, engineers have no internal dashboard to immediately view the active on-call engineer, review open incident timelines, acknowledge pages, or execute emergency maintenance overrides from a centralized UI.

SiteSwarm’s retention model relies on demonstrating continuous business value to local owners (traffic growth, lead conversions, mobile performance). Today, pageview metrics, Web Vitals, and lead intake counts reside in disparate databases and edge logs. Agency staff lack a consolidated view to audit client traffic health, verify SEO performance, or detect conversion drops before clients notice.

To scale sustainably, SiteSwarm requires a unified, internal Central Command Center (apps/command-center) providing a single pane of glass for agency employees across CMS operations, platform uptime, incident management, and client telemetry.

2. Decision Drivers

We establish the following non-negotiable architectural criteria:

Single-Pane-of-Glass Operations: Agency staff must be able to switch between any client tenant, inspect operational health, edit CMS content, view active incidents, and review visitor telemetry from a single interface.
Zero Daytime Maintenance Footprint: The Command Center must deploy as an edge-native serverless application on Cloudflare Workers, requiring zero persistent VPS management, zero container patching, and near-zero idle cost.
Monorepo Architectural Cohesion: The application must live within the monorepo (apps/command-center), adhering to established SiteSwarm conventions: Astro SSR + React, Tailwind CSS, @siteswarm/components design tokens, and shared TypeScript contracts.
Provider-Agnostic Abstraction Layer: Fleet observability, synthetic probes, on-call schedules, and active incident lifecycles must be decoupled behind clean internal adapter interfaces, ensuring compatibility with any monitoring backend (Cloudflare-native D1/KV, BetterStack, Datadog, or self-hosted open-source tooling).
Zero-Latency Backend-For-Frontend (BFF): Internal communication between the Command Center and core platform services (services/cms-service, services/leads-service, services/synthetic-monitoring) must leverage 0ms Cloudflare Service Bindings in-memory RPC, completely eliminating public Internet hops and API token leakage.
Ironclad Perimeter Security & RBAC: The Command Center exposes fleet-wide administrative controls and must be protected by Cloudflare Zero Trust (Access) at the edge, supplemented by cryptographic JWT assertion verification and granular Role-Based Access Control (Admin, Support Engineer, Content Editor).
Extensible Modular Shell: The dashboard architecture must be designed as an extensible plugin/micro-app shell so future operational capabilities (e.g. Stripe client billing, ephemeral PR preview management, and AI agent critique reviews) can be plugged in without refactoring core layouts.

3. The Decision: Bespoke Monorepo Command Center (`apps/command-center`)

We formally decide to build the SiteSwarm Central Command Center as a bespoke internal platform web application residing in apps/command-center, powered by Astro SSR + React & Tailwind CSS, hosted on Cloudflare Workers, protected by Cloudflare Zero Trust (Access), and integrated via an Edge Backend-For-Frontend (BFF) with 0ms Cloudflare Service Bindings.

flowchart TD
    subgraph Users["SiteSwarm Agency Staff (Employees Only)"]
        Admin["Platform Admin"]
        Support["Support Engineer"]
        Editor["Content Editor"]
    end

    subgraph Perimeter["Edge Security Perimeter"]
        CF_Access["Cloudflare Zero Trust (Access)\n• Google Workspace / GitHub SSO\n• MFA / Hardware Passkeys\n• Domain: ops.siteswarm.dev"]
        JWT_Verify["Edge JWT Assertion Guard\n(Cf-Access-Jwt-Assertion & RBAC)"]
    end

    subgraph CommandCenter["apps/command-center (Cloudflare Worker Isolate)"]
        direction TB
        subgraph Shell["Astro SSR + React Frontend Shell"]
            Nav["Workspace Shell & Tenant Switcher"]
            Palette["Quick Actions (Cmd + K)"]
            subgraph Views["Pluggable Operational Modules"]
                M1["1. Mission Control Overview"]
                M2["2. CMS Fleet Studio"]
                M3["3. Fleet Health & Uptime"]
                M4["4. Incident Ops & On-Call"]
                M5["5. Telemetry & Analytics Explorer"]
            end
        end

        subgraph EdgeBFF["Edge Backend-For-Frontend (BFF) Layer"]
            BFF_Router["Hono / Astro API Router (/api/*)"]
            RBAC_Engine["RBAC Authorization Engine"]
            Cache_Layer["Edge Memory Cache (SWR)"]
            Adapter_Mesh["Provider-Agnostic Adapter Mesh"]
        end
    end

    subgraph PlatformServices["Internal Platform Workers (0ms Service Bindings)"]
        CMS_Service["services/cms-service\n(Multi-Tenant Content Engine)"]
        Monitor_Service["services/synthetic-monitoring\n(Synthetic Probes & Health D1)"]
        Leads_Service["services/leads-service\n(Lead CRM & Antispam Logs)"]
    end

    subgraph ExternalAdapters["External Provider Adapters"]
        Incident_Provider["BetterStack / Webhook Router\n(On-Call Roster & Incident Pages)"]
        Tail_Worker["Cloudflare Tail Workers\n(Edge Error Exception Stream)"]
        Analytics_Engine["Cloudflare Analytics Engine / SQL API\n(Visitor Telemetry & Web Vitals)"]
    end

    subgraph ClientFleet["Decoupled Client Fleet (Worker B: CMS Isolates)"]
        ClientBakery["Worker B: green-leaf-bakery-cms"]
        ClientAgency["Worker B: software-agency-cms"]
        ClientAuto["Worker B: auto-repair-cms"]
    end

    Users -->|HTTPS Request| CF_Access
    CF_Access --> JWT_Verify
    JWT_Verify --> CommandCenter

    Shell --> EdgeBFF
    EdgeBFF -->|"env.CMS_SERVICE.fetch() (0ms)"| CMS_Service
    EdgeBFF -->|"env.MONITOR_SERVICE.fetch() (0ms)"| Monitor_Service
    EdgeBFF -->|"env.LEADS_SERVICE.fetch() (0ms)"| Leads_Service

    Adapter_Mesh --> Incident_Provider
    Adapter_Mesh --> Tail_Worker
    Adapter_Mesh --> Analytics_Engine

    CMS_Service -.->|"Cross-Tenant D1 / Direct Binding"| ClientBakery
    CMS_Service -.->|"Cross-Tenant D1 / Direct Binding"| ClientAgency
    CMS_Service -.->|"Cross-Tenant D1 / Direct Binding"| ClientAuto

4. Deep-Dive Subsystem Architecture

4.1 CMS Fleet Studio & Multi-Tenant Management Engine

The Command Center provides a Unified Multi-Tenant Content Studio eliminating the need for employees to log in to separate client sites:

sequenceDiagram
    autonumber
    actor Employee as Agency Employee
    participant UI as Command Center UI (apps/command-center)
    participant BFF as Edge BFF (/api/cms/*)
    participant CMS as services/cms-service
    participant D1 as Client D1 Database
    participant Purge as Cloudflare Cache Purge API
    participant ClientA as Worker A (Live Public Frontend)

    Employee->>UI: Select Tenant: "green-leaf-bakery"
    UI->>BFF: GET /api/cms/content?tenant=green-leaf-bakery
    BFF->>CMS: env.CMS_SERVICE.fetch() [tenantId: green-leaf-bakery]
    CMS->>D1: Query hours, banners, menus, SEO schemas
    D1-->>CMS: Return JSON records
    CMS-->>BFF: Validated Content Payload
    BFF-->>UI: Render Dynamic Studio Schema

    Employee->>UI: Modify Holiday Hours & Click "Publish Globally"
    UI->>BFF: POST /api/cms/content [tenantId, payload]
    BFF->>CMS: env.CMS_SERVICE.fetch() [Write Action]
    CMS->>D1: Execute atomic SQL transaction
    D1-->>CMS: Commit Confirmed
    CMS->>Purge: Purge Cache-Tags: ["tenant:green-leaf-bakery"]
    Purge-->>CMS: Cache Purged Globally (<150ms)
    CMS-->>BFF: 200 OK (Write & Invalidation Confirmed)
    BFF-->>UI: Toast: "Published & Purged across Edge in 1.1s"

    Note over Employee,UI: 1-Click SSO Launchpad Option
    Employee->>UI: Click "Open as Client Admin"
    UI->>BFF: POST /api/cms/impersonate?tenant=green-leaf-bakery
    BFF-->>UI: Returns signed short-lived magic session URL
    UI->>ClientA: Launches https://greenleafbakery.com/_emdash/admin

Core CMS Studio Capabilities:

Fleet Switcher: Instant tenant selector with fuzzy search (apps/bakery, apps/software-agency, apps/auto-repair, etc.).
Schema-Driven Direct Editing: Ingests the client’s declared EmDash schemas to generate high-speed input forms for operating hours, emergency banners, announcements, staff profiles, and pricing tables.
Instant Cache-Tag Invalidation: Every write triggers targeted edge cache purging via the Content Invalidation Bridge (ADR-0003), propagating changes worldwide in under 150ms.
1-Click Magic SSO Launchpad: For deep visual or complex markdown editing, generates a cryptographically signed, short-lived (5-minute) admin session token redirecting the employee directly into the client’s standalone EmDash studio (client.com/_emdash/admin) without re-authenticating.

4.2 Fleet Health & Synthetic Observability (Provider-Agnostic Adapter Pattern)

Following our consensus, the Command Center UI does not hardcode a specific monitoring vendor. Instead, it interacts exclusively with an abstracted Observability & Health Gateway:

export type HealthSeverity = 'ok' | 'degraded' | 'error' | 'critical';

export interface ClientAppHealth {
  appId: string;
  displayName: string;
  primaryDomain: string;
  environment: 'production' | 'staging' | 'preview';
  status: HealthSeverity;
  commitSha: string;
  uptime24h: number; // 99.98%
  uptime30d: number; // 99.95%
  latencyP95Ms: number;
  databaseStatus: 'connected' | 'disconnected' | 'not_configured';
  lastProbeTimestamp: string;
  failingChecks: string[];
}

export interface ObservabilityAdapter {
  getFleetHealth(): Promise<ClientAppHealth[]>;
  getAppHealth(appId: string): Promise<ClientAppHealth>;
  getEdgeExceptionFeed(limit: number): Promise<EdgeExceptionEvent[]>;
}

Multi-Tier Implementation Strategy:

Baseline (Platform Native): Queries services/synthetic-monitoring via Cloudflare Service Binding. The worker runs scheduled cron probes (*/2 * * * *) executing HTTP requests against all enrolled client /api/health endpoints, saving probe outcomes into a central Cloudflare D1 table.
Edge Exception Stream: Ingests real-time unhandled worker exceptions and HTTP 5xx spikes captured via Cloudflare Tail Workers.
Future Vendor Expansion: If SiteSwarm adopts BetterStack, Datadog, or an open-source Uptime Kuma instance, developers simply implement the ObservabilityAdapter interface without modifying any frontend React/Astro components.

4.3 Incident Operations & On-Call Escalation Center

To prevent daytime panic and streamline off-hours incident response, the Command Center incorporates an Incident Ops Center backed by an incident adapter:

export interface OnCallShift {
  primaryEngineer: { name: string; email: string; phone: string; avatarUrl?: string };
  secondaryEngineer?: { name: string; email: string; phone: string };
  shiftStart: string;
  shiftEnd: string;
  escalationPolicy: string;
}

export interface ActiveIncident {
  id: string;
  title: string;
  severity: 'P1' | 'P2' | 'P3';
  status: 'investigating' | 'identified' | 'monitoring' | 'resolved';
  impactedApps: string[];
  openedAt: string;
  acknowledgedAt?: string;
  acknowledgedBy?: string;
  summary: string;
  timelineUrl?: string;
}

export interface IncidentAdapter {
  getCurrentOnCall(): Promise<OnCallShift>;
  getActiveIncidents(): Promise<ActiveIncident[]>;
  acknowledgeIncident(incidentId: string, employeeEmail: string): Promise<void>;
  resolveIncident(incidentId: string, resolutionSummary: string): Promise<void>;
}

Incident Management Capabilities:

Live On-Call Badge: Always-visible top navigation badge displaying the primary on-call engineer and escalation countdown.
Triage & Acknowledgment Queue: Active P1/P2/P3 incidents surfaced on the main dashboard with 1-click “Acknowledge” and “Resolve” triggers bridging to BetterStack / PagerDuty / Webhook routers.
Incident Blast Containment: Quick-action toggles to put degraded client applications into graceful static fallback or display an emergency maintenance banner while investigating.

4.4 Client Telemetry & Analytics Explorer

As clarified during architectural grilling, the underlying analytics collection engine (beacon ingestion, clickstream schemas, ClickHouse vs. Analytics Engine) is governed under a separate downstream ADR.

The Command Center defines a clean Analytics Dashboard Consumer Adapter:

Fleet Aggregate Telemetry: Total monthly pageviews, unique visitors, total lead inquiries captured, and spam submissions blocked across all client applications.
Per-Tenant Deep Dive:
- Visitor traffic trends over 24h / 7d / 30d / 90d.
- Top visited pages (/menu, /services, /about).
- Conversion funnels (Form views -> Turnstile pass -> Lead submissions).
- Core Web Vitals rollup (Largest Contentful Paint < 1.2s, Cumulative Layout Shift 0.00, Interaction to Next Paint < 50ms).
Data Source Agnosticism: Feeds from services/analytics-service (Cloudflare Analytics Engine SQL API) with the capability to consume self-hosted Umami, Plausible, or Tinybird via adapter swap.

5. Extensible Modular Shell Architecture

To fulfill our requirement that the Command Center scale to incorporate future capabilities without structural rewrites, the shell is built on a Pluggable Micro-App Tab Model:

flowchart LR
    Shell["Command Center Shell\n(Auth, Navigation, Tenant Selector, Cmd+K)"]

    subgraph CoreModules["Wave 1 Modules (Approved in ADR-0004)"]
        M1["1. Mission Control Overview"]
        M2["2. CMS Fleet Studio"]
        M3["3. Fleet Health & Uptime"]
        M4["4. Incident Ops & On-Call"]
        M5["5. Telemetry & Analytics"]
    end

    subgraph FutureModules["Wave 2 & 3 Expansion Modules"]
        M6["6. Ephemeral PR Previews & Deployments"]
        M7["7. Client Billing & Stripe Shield"]
        M8["8. AI Agent Critique & Scaffolding Studio"]
        M9["9. Lead CRM & Inbound Pipeline"]
    end

    Shell --> CoreModules
    Shell -.->|Pluggable Route Manifest| FutureModules

Module Registration Contract:

export interface CommandCenterModule {
  id: string;
  name: string;
  icon: string;
  path: string;
  requiredRole: 'admin' | 'support' | 'editor';
  badgeValue?: () => Promise<string | number | null>;
  renderWidget?: () => React.ReactElement;
}

Each module operates as an independent sub-route (/cms, /health, /incidents, /analytics, /billing, /deployments) with its own Astro server endpoints and React component trees, isolated from sibling module regressions.

5.1 Dual-Surface Capability Strategy: The EmDash Plugin Commercialization Flywheel

A vital strategic advantage of SiteSwarm’s architecture is the Agency-to-Client Commercialization Flywheel: capabilities engineered to streamline internal agency operations are packaged as high-margin, recurring software upsells for local business clients.

Every client application already hosts an isolated EmDash CMS instance in Worker B (client.com/admin or client.com/_emdash/admin) per ADR-0003. Rather than locking operational logic inside apps/command-center, all client-relevant operational modules (Analytics, Lead Management, Uptime Status, Customer Reviews) are authored as dual-surface capability packages in packages/plugins/* adhering to @emdash-cms/plugin-types.

flowchart TD
    subgraph Development["Unified Capability Development (packages/plugins/*)"]
        Core["Headless Capability Engine\n(packages/plugins/<name>/src/core)"]
    end

    subgraph InternalSurface["Internal Agency Surface: apps/command-center"]
        CC["Executive Fleet Cockpit\n• Multi-Tenant Fleet Aggregates\n• Anomaly Detection & Alerts\n• Panoramic Health Matrix"]
    end

    subgraph ClientSurface["Client Commercial Surface: client.com/admin"]
        CMS["Client EmDash Studio (Worker B)\n• Privacy-First Traffic Cards\n• Self-Serve Lead CRM Table\n• Live Uptime Trust Badge"]
    end

    subgraph Monetization["Commercial Packaging & Retainers"]
        M1["Base Plan ($0/mo Included)"]
        M2["Content Retainer ($99/mo)"]
        M3["Growth Retainer ($199/mo)"]
        M4["A La Carte Plugin ($29-$49/mo)"]
    end

    Core --> InternalSurface
    Core --> ClientSurface
    ClientSurface --> Monetization

Standardized Plugin Package Anatomy (`packages/plugins/*`):

packages/plugins/analytics/
├── package.json                    # Workspace package (@siteswarm/plugin-analytics)
├── emdash-plugin.jsonc             # Plugin manifest (@emdash-cms/plugin-types)
├── src/
│   ├── index.ts                    # Root export: core contracts + emdash + command-center
│   ├── core/                       # 1. Headless Business Logic & Contracts
│   │   ├── types.ts                # Metric intervals, Web Vitals, pageview types
│   │   ├── client.ts               # Cloudflare Analytics Engine / D1 SQL query client
│   │   └── aggregator.ts           # Trend calculations, bounce rate, conversion math
│   ├── emdash/                     # 2. Client EmDash Plugin (@emdash-cms/plugin-types)
│   │   ├── plugin.ts               # definePlugin({ id, version, routes, admin, hooks })
│   │   ├── admin-widget.ts         # Block Kit dashboard widget for client /admin
│   │   └── routes.ts               # /_emdash/api/plugins/analytics/overview
│   └── command-center/             # 3. Agency Command Center View (apps/command-center)
│       ├── FleetAnalyticsGrid.tsx  # Multi-tenant comparison table across all clients
│       └── TenantDeepDiveView.tsx  # Time-series charts, Web Vitals, funnels

Reusable Plugin Commercial Catalog:

@siteswarm/plugin-analytics:
- Internal Agency Use: Fleet-wide traffic rollups, conversion drop alerts, and traffic anomaly detection.
- Client Commercial Upsell: Zero-cookie, GDPR-compliant visitor analytics directly inside client /admin ($29/mo or included in $99/mo Content Retainer).
@siteswarm/plugin-leads:
- Internal Agency Use: Fleet-wide form submission monitoring, spam rejection rates, and Twilio/Resend webhook delivery status.
- Client Commercial Upsell: Built-in mini-CRM for bakery catering orders, quote inquiries, and repair bookings ($49/mo or included in $199/mo Growth Retainer).
@siteswarm/plugin-status:
- Internal Agency Use: Synthetic health probe telemetry and latency history.
- Client Commercial Upsell: Branded “99.98% Edge Uptime” trust badge in CMS + public /status page (Included in Base to reinforce trust).

6. Security, Zero Trust Perimeter & Role-Based Access Control (RBAC)

Because the Command Center governs dynamic content, database schemas, and platform incident states across all client businesses, perimeter security is paramount.

sequenceDiagram
    autonumber
    actor Staff as SiteSwarm Employee
    participant Browser as Employee Browser
    participant Access as Cloudflare Zero Trust (Access)
    participant Worker as apps/command-center (Edge Worker)
    participant BFF as Command Center BFF Router

    Staff->>Browser: Navigate to ops.siteswarm.dev
    Browser->>Access: GET / (Perimeter Ingress)
    Access->>Browser: Enforce SSO (Google Workspace / GitHub OAuth + Passkey)
    Browser->>Access: Submit Verified Auth Credentials
    Access->>Access: Validate Policy (Email in @siteswarm.com group)
    Access->>Browser: Set CF_Authorization Cookie
    Access->>Worker: Dispatch with Cf-Access-Jwt-Assertion Header

    Worker->>Worker: Cryptographically Validate Access JWT against Cloudflare Public Certs (CERTS URL)
    Worker->>Worker: Extract User Email & Lookup Assigned Role in RBAC Manifest

    alt Insufficient Role (e.g. Editor accessing /incidents/resolve)
        Worker-->>Browser: 403 Forbidden (RBAC Access Denied)
    else Authorized
        Worker->>BFF: Execute Route Handler with Verified Identity Context
        BFF-->>Browser: Render Authorized Command Center UI
    end

6.1 Role-Based Access Control (RBAC) Matrix

Capability / Operational Action	Content Editor (`editor`)	Support Engineer (`support`)	Platform Admin (`admin`)
View Mission Control Overview	🟢 Allowed	🟢 Allowed	🟢 Allowed
Inspect Dynamic CMS Content	🟢 Allowed	🟢 Allowed	🟢 Allowed
Edit & Publish CMS Content	🟢 Allowed	🟢 Allowed	🟢 Allowed
Trigger Edge Cache Purge	🟢 Allowed	🟢 Allowed	🟢 Allowed
Inspect Fleet Health & Probes	❌ Denied	🟢 Allowed	🟢 Allowed
View Edge Exception Logs	❌ Denied	🟢 Allowed	🟢 Allowed
Acknowledge / Triage Incidents	❌ Denied	🟢 Allowed	🟢 Allowed
Resolve Platform Incidents	❌ Denied	⚠️ Escalate	🟢 Allowed
Execute Emergency Maintenance Override	❌ Denied	❌ Denied	🟢 Allowed
Manage Billing, Plans & Stripe Shield	❌ Denied	❌ Denied	🟢 Allowed
Trigger Fleet-Wide CI/CD Deployments	❌ Denied	❌ Denied	🟢 Allowed

7. Evaluated Contenders & Comparative Architecture Matrix

To select the definitive platform architecture, we evaluated four primary solutions:

Architectural Dimension	Contender 1: Bespoke Astro/React Shell + Dual-Surface Plugins [ADOPTED]	Contender 2: Open-Source Internal Tool (Refine / ToolJet)	Contender 3: Federated Launchpad / Iframe Aggregator	Contender 4: Pure Employee EmDash Meta-CMS
Runtime Topology	Cloudflare Workers Edge SSR (`apps/command-center`)	Long-running Node.js / Docker container (Fly.io / VPS)	Static portal redirecting to third-party SaaS consoles	Standard EmDash instance on Workers (`emdash` + `@emdash-cms/cloudflare`)
Internal RPC Latency	0ms in-process Cloudflare Service Bindings	100ms–300ms public network API hops	N/A (Cross-origin navigation)	Service Bindings / D1 HTTP API
Daytime Server Upkeep	Zero upkeep (Serverless edge)	High (Container patches, VPS maintenance, DB scaling)	Zero upkeep	Zero upkeep (Serverless edge)
Operational Ergonomics	🟢 Optimized for Ops: Panoramic matrix, live on-call badges, keyboard triage (`Cmd+K`)	🟡 Moderate: Standard internal CRUD forms	🔴 Poor: Context switching across 5 vendor dashboards	🔴 Awkward: Treating synthetic probes, incidents, and telemetry as CMS collection records
Visualization Surface	🟢 Unconstrained: Native React, Canvas/SVG charts, Web Vitals gauges, log streams	🟡 Generic chart widgets	🟡 Vendor dashboard embeds	🔴 Constrained: Sandboxed Block Kit forms; lacks native rich time-series chart rendering
Subrequest & Quota Limits	🟢 Safe: Heavy tasks offloaded to platform microservices (`services/*`)	🟢 Safe (Unconstrained server)	🟢 Safe (Client-side)	🔴 Risky: Concurrently probing 50+ clients inside CMS worker risks 50 subrequest/invocation caps
Client Upsell Leverage	🟢 Maximum: Dual-surface packages (`packages/plugins/*`) deliver client upsells	🔴 Zero: Internal tool code cannot run in client CMS	🔴 Zero: No shared plugin surface	🟢 High: Capabilities naturally package as EmDash plugins
Single Sign-On UX	Unified Cloudflare Access SSO session	Separate login database or enterprise SAML plugin	Requires logging into 4 distinct vendor portals	Cloudflare Access + EmDash Session Auth
Monthly Hosting Cost	$0 extra (Bundled in Cloudflare Workers Paid plan)	$15–$50/mo (Compute container + managed Postgres)	Free to $50/mo in SaaS tier fees	$0 extra (Bundled in Cloudflare Workers Paid plan)
Architectural Verdict	🟢 APPROVED & ADOPTED AS CANONICAL ARCHITECTURE	❌ REJECTED (Violates zero-maintenance thesis)	❌ REJECTED (Fragmented employee UX)	⚠️ PARTIALLY ADOPTED VIA DUAL-SURFACE PLUGINS (§5.1): Rejected as standalone cockpit; adopted for plugin catalog

8. Consequences & Trade-offs

Positive Consequences

True Single Pane of Glass: Eliminates context switching across disparate client hostnames, Cloudflare consoles, and monitoring alerts.
Zero Daytime Maintenance: Leverages Cloudflare Workers serverless edge execution with 0 server instances to patch or restart during day jobs.
0ms Internal RPC: Service bindings connect the Command Center to platform microservices with zero network hop latency and zero exposed secrets.
Strict Perimeter Isolation: Entire platform shielded behind Cloudflare Zero Trust with verified JWT assertion headers.
Future-Proof Extensibility: Modular plugin structure allows seamless addition of billing, preview management, and AI agent critique tabs.

Negative Consequences / Trade-offs

Custom UI Maintenance: Building and maintaining a custom Astro/React platform app requires dedicated engineering investment compared to using an off-the-shelf SaaS tool.
Edge Runtime Constraints: All BFF routes execute in V8 isolate environments (Cloudflare Workers), requiring Node.js compatibility flags and preventing the use of heavy native Node.js binaries.
Multi-Worker Local Development: Developing the Command Center locally requires running Wrangler with multiple service binding declarations or local mock handlers.

9. Phased Implementation Roadmap & Sequenced Milestones

We organize execution into five structured phases:

flowchart LR
    P1["Phase 1: Shell Scaffolding & Zero Trust\n(Astro SSR, RBAC, Layout)"]
    P2["Phase 2: CMS Fleet Studio\n(Tenant Switcher, Service Binding)"]
    P3["Phase 3: Fleet Health Gateway\n(Synthetic Probes, Tail Exceptions)"]
    P4["Phase 4: Incident Ops & On-Call\n(BetterStack / Webhook Bridge)"]
    P5["Phase 5: Telemetry Explorer & Extensions\n(Analytics Ingestion, Billing)"]

    P1 --> P2 --> P3 --> P4 --> P5

Phase 1: Shell Scaffolding & Edge Zero Trust Ingress

Scaffold apps/command-center using Astro SSR (@astrojs/cloudflare) with React and Tailwind CSS.
Configure wrangler.jsonc with Node.js compatibility and compatibility date.
Implement Cloudflare Access JWT validation middleware with cryptographic signature check and RBAC claim mapping.
Author standard layout shell with header, sidebar, breadcrumbs, command palette (Cmd+K), and user profile badge.

Phase 2: CMS Fleet Studio & Service Binding Gateway

Bind CMS_SERVICE (services/cms-service) to apps/command-center via Cloudflare Service Bindings.
Build the Fleet Tenant Selector component populated from @siteswarm/governance app registry.
Implement dynamic schema form builder for quick updates (hours, announcements, banners, contact info).
Wire the Content Invalidation Bridge button to trigger edge cache purges with visual confirmation.
Author the 1-click signed SSO launchpad to jump into the client’s live /admin studio.

Phase 3: Fleet Health & Synthetic Observability Console

Bind MONITOR_SERVICE (services/synthetic-monitoring) to apps/command-center.
Implement ObservabilityAdapter interface and default Cloudflare D1 probe history provider.
Author Fleet Health grid displaying live /api/health status, commit SHA, latency, and DB connectivity.
Build Edge Exception log drawer streaming unhandled worker exceptions from Tail Workers.

Phase 4: Incident Ops & On-Call Escalation Center

Implement IncidentAdapter interface with BetterStack / Webhook router provider.
Build live On-Call Shift header badge and active incident queue.
Implement 1-click Acknowledge and Resolve modal dialogs with incident timeline tracking.
Provide emergency maintenance mode toggles for individual client applications.

Phase 5: Telemetry Dashboard Consumer & Future Module Expansion

Implement AnalyticsAdapter interface consuming services/analytics-service / Cloudflare Analytics Engine SQL API.
Render fleet-wide and per-client traffic charts, Web Vitals gauges, and lead conversion metrics.
Prepare module extension slots for downstream Epics: Ephemeral PR Preview Management, Client Stripe Billing Shield, and AI Agent Critiques.

ADR-0004: Central Command Center Architecture

ADR-0004: Central Command Center Architecture

1. Context & Problem Statement

1.1 The Fragmented Multi-Tenant CMS Problem

1.2 The Fragmented Observability & Health Visibility Problem

1.3 The Disconnected Incident & On-Call Triage Flow

1.4 The Telemetry & Client Analytics Blind Spot

2. Decision Drivers

3. The Decision: Bespoke Monorepo Command Center (apps/command-center)

4. Deep-Dive Subsystem Architecture

4.1 CMS Fleet Studio & Multi-Tenant Management Engine

Core CMS Studio Capabilities:

4.2 Fleet Health & Synthetic Observability (Provider-Agnostic Adapter Pattern)

Multi-Tier Implementation Strategy:

4.3 Incident Operations & On-Call Escalation Center

Incident Management Capabilities:

4.4 Client Telemetry & Analytics Explorer

5. Extensible Modular Shell Architecture

Module Registration Contract:

5.1 Dual-Surface Capability Strategy: The EmDash Plugin Commercialization Flywheel

Standardized Plugin Package Anatomy (packages/plugins/*):

Reusable Plugin Commercial Catalog:

6. Security, Zero Trust Perimeter & Role-Based Access Control (RBAC)

6.1 Role-Based Access Control (RBAC) Matrix

7. Evaluated Contenders & Comparative Architecture Matrix

8. Consequences & Trade-offs

Positive Consequences

Negative Consequences / Trade-offs

9. Phased Implementation Roadmap & Sequenced Milestones

Phase 1: Shell Scaffolding & Edge Zero Trust Ingress

Phase 2: CMS Fleet Studio & Service Binding Gateway

Phase 3: Fleet Health & Synthetic Observability Console

Phase 4: Incident Ops & On-Call Escalation Center

Phase 5: Telemetry Dashboard Consumer & Future Module Expansion

3. The Decision: Bespoke Monorepo Command Center (`apps/command-center`)

Standardized Plugin Package Anatomy (`packages/plugins/*`):