SiteSwarm — Product Requirements Document (PRD)

SiteSwarm — Product Requirements Document (PRD)

Document Status: Approved / Living True Product Specification
Target Audience: Core Engineering, Product Strategy, and Autonomous AI Agent Contributors
Related Documents: README.md, HIGH_LEVEL_DESIGN.md, docs/CAPABILITY_MANAGEMENT.md

---

1. Executive Summary & Strategic Objective

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

1.1 The Market Opportunity

Local businesses (independent bakeries, auto repair shops, specialty medical clinics, community service providers) are fundamentally underserved by the modern web ecosystem:

1. Generic Website Builders (Squarespace, Wix, WordPress): Deliver cookie-cutter templates that become fragile, slow, and impossible to customize as soon as the business requires bespoke workflows, high-performance edge rendering, or specialized third-party integrations.
2. Traditional Web Agencies: Demand prohibitive upfront capital ($5,000–$25,000+) and expensive monthly retainers ($500–$2,000/mo) that price out independent local shops.

SiteSwarm dissolves this false dilemma. We provide local small businesses with custom-tailored, enterprise-grade web applications featuring modern bespoke design, instant edge performance, and tailored functionality. We accomplish this not by cutting corners, but by anchoring our work in a monolithic backbone where every tooling enhancement, security audit, accessibility gate, and workflow automation is shared across the entire fleet of client applications.

1.2 The Dual-Engine Operating Thesis

SiteSwarm is specifically engineered for software engineers who maintain demanding daytime roles while building and scaling a thriving local software agency during off-hours:

flowchart LR
    subgraph Day["Daytime: Career & Focus"]
        direction TB
        D1["Full-Time Software Engineering Career"]
        D2["Zero Operational Anxiety"]
        D3["Zero Daytime Client Interruptions"]
    end

    subgraph Guardrails["Automated Guardrails & CMS"]
        direction TB
        G1["Modern Cloud Platform (e.g. Cloudflare)"]
        G2["Mandatory Client CMS for Routine Updates"]
        G3["Synthetic Health Probes & Alarms"]
    end

    subgraph Night["Off-Hours: High-Velocity Growth"]
        direction TB
        N1["Local Community Discovery & Pitches"]
        N2["Agent-Assisted Scaffolding & Bespoke UI"]
        N3["Capability Extraction to Shared Catalog"]
    end

    Day --- Guardrails --- Night

---

2. Core Target Personas & User Journeys

SiteSwarm is optimized around three primary personas whose interactions define the platform requirements.

2.1 The Daytime Engineer

• Profile: Experienced software engineer with a demanding daytime career. Available for agency work primarily during off-hours (evenings and weekends).
• Core Need: Absolute peace of mind during business hours. Zero tolerance for fragile servers, unexpected downtime alerts, or client phone calls asking for routine text changes.
• Platform Experience:
  • Leverages AI coding agents to scaffold complete applications and author bespoke UI in minutes.
  • Relies on automated CI evaluation suites (accessibility, performance, edge compatibility) to catch defects before human review.
  • Never serves as a manual content updater for clients; routine edits are self-served by clients via an intuitive CMS.

2.2 The Local Business Owner

• Profile: Owner or general manager of a local brick-and-mortar business (e.g., bakery, auto repair, dental clinic). Non-technical, busy running daily operations, highly sensitive to visual identity and customer reputation.
• Core Need: A unique digital presence that looks distinct from competitors, loads instantly on smartphones, converts visitors into customers, and doesn’t cost an arm and a leg.
• Platform Experience:
  • Reviews interactive previews of their site on their personal smartphone via an ephemeral PR URL within 24–48 hours of onboarding.
  • Manages Business-As-Usual (BAU) content updates (holiday hours, daily menus, staff announcements) independently through a client CMS without waiting on or paying an engineer.
  • Gains access to high-value capabilities (online booking, turnstile lead capture, dynamic inventory) as modular platform upgrades.

2.3 The AI Coding Agent

• Profile: Autonomous or semi-autonomous AI coding agent operating inside isolated Git worktrees (wt).
• Core Need: Machine-readable governance manifests, unambiguous architectural boundaries, and immediate compile-time and lint-time feedback loops.
• Platform Experience:
  • Introspects @siteswarm/governance contracts (swarm.config.ts) to discover available platform capabilities and locate client target files.
  • Generates bespoke, unconstrained HTML/CSS/Astro UI tailored to the client’s brand.
  • Operates against unforgiving static linters and test runners (pnpm swarm audit, headless accessibility checks, Lighthouse budgets) to self-correct code before human review.

---

3. Foundational Product Principles & Theses

3.1 Thesis: “Bespoke UI is Free / Evaluation Gates are Mandatory”

Traditional agencies treat UI components (navbars, cards, footers, form controls) as expensive assets that must be standardized into a shared component library or theme adapter.

SiteSwarm rejects rigid visual UI component adapters and cookie-cutter themes in favor of bespoke visual design paired with shared headless code libraries.

• Generating visual UI is cheap and instant with AI: AI coding agents can generate beautiful, bespoke markup and styling from scratch in seconds. Reusing rigid visual UI components across clients introduces artificial constraints, leads to visual monotony (“all agency sites look identical”), and causes tight coupling where updating a shared button style risks breaking unrelated client sites.
• Each client receives a 100% unique, bespoke digital experience: Application layouts, typography, animations, and visual styling in apps/<client>/ are completely unshared and tailored to the client’s identity.
• Shared code libraries provide leverage where it counts: Rejecting visual component adapters does not mean avoiding shared code. Headless capability packages (@siteswarm/*), unstyled accessibility primitives, shared TypeScript contracts, and utility libraries in packages/* provide compounding leverage across the fleet.
• Shared tooling acts as an automated quality gatekeeper: The true shared asset in SiteSwarm is not visual UI components, but the unforgiving evaluation suite (linters, headless accessibility tests, mobile performance budgets, and security scanners) that validates massive volumes of AI-generated code before it reaches production.

flowchart TD
    subgraph Traditional["Traditional Shared Component Model (Rejected)"]
        TC1["Shared UI Component Library"] --> TC2["Theme Adapters & Token Overrides"]
        TC2 --> TC3["Visual Monotony & Coupling Risk"]
    end

    subgraph SiteSwarm["SiteSwarm Bespoke UI & Evaluation Gatekeeper Model (Adopted)"]
        SC1["AI Agent Generates 100% Bespoke UI per Client"] --> SC2["Independent apps/<client> UI (Astro/HTML/CSS)"]
        SC2 --> SC3["Automated Quality Gatekeepers in CI"]
        SC3 --> SC4["WCAG 2.1 AA Accessibility Gate"]
        SC3 --> SC5["Mobile Performance Budget Gate (Lighthouse >= 95)"]
        SC3 --> SC6["Cloudflare Edge Runtime Compatibility Gate"]
        SC3 --> SC7["Schema.org SEO & Semantic HTML Gate"]
    end

3.2 Thesis: Mandatory Client CMS for Routine Content (BAU)

To preserve the Daytime Engineer’s zero-anxiety operating model, engineers must never act as a bottleneck for everyday content updates.

3.2.1 The Real-Time Mobile Update Problem

Small business owners frequently experience operational changes that require immediate public notice:

• An artisan bakery sells out of morning pastries at 8:15 AM.
• A dental clinic closes unexpectedly at 7:00 AM due to a severe snowstorm.
• A mechanic updates holiday hours or posts a seasonal tire-swap special.

If updating these notices requires contacting an engineer, filing a ticket, or waiting through a multi-minute Git commit and CI build pipeline, the process breaks down. The owner gets frustrated, and the daytime engineer is interrupted during work hours.

3.2.2 Solution Mandate & Candidate Evaluation

Every client application must provide an intuitive, mobile-friendly CMS interface for routine Business-As-Usual (BAU) edits. The True Specification (docs/CLIENT_CMS.md) defines the unified EmDash CMS architecture (Astro + Workers + D1 + R2) evaluating candidate solutions spanning:

1. Open-Source Headless / Git-Backed CMS Options: Assessing established contenders (such as Decap CMS, TinaCMS, Keystatic, or Payload CMS).
2. Hand-Rolled Lightweight Edge Admin: Assessing an agency-crafted edge administrative route storing live overrides directly in edge state (KV/D1).

3.2.3 Evaluation Criteria for CMS Selection

Any adopted solution must be scored against five strict product constraints:

• Mobile Usability: The business owner must be able to log in and toggle an announcement or update text from their smartphone in under 60 seconds.
• Propagation Speed: Changes to emergency notices or daily specials should reflect on the live site almost immediately (under 5 seconds), ideally without triggering a full rebuild of the static site.
• Zero Daytime Interventions: Content errors, formatting quirks, or CMS updates must never fail in a manner that requires human engineering triage during business hours.
• Authentication Simplicity: Non-technical clients must authenticate painlessly (e.g. magic link or PIN) without requiring GitHub accounts or complex credential handshakes.
• Operational Maintenance Footprint: The CMS runtime must not introduce fragile server dependencies or heavy database upkeep.

3.3 Thesis: Runtime Independence with Build-Time Leverage

• Monolithic at Build Time: A single repository consolidates CI pipelines, linter definitions, capability contracts, and deployment scripts. Improvements made to verification tooling immediately protect the entire fleet.
• Isolated at Runtime: Every client application deploys as an independent, decoupled service on modern edge infrastructure (e.g., Cloudflare Pages/Workers). A traffic surge or catastrophic runtime error in Client A never degrades Client B.

3.4 Thesis: Proactive Observability over Reactive Support

• Client sites are continuously monitored by synthetic health checks and edge probes.
• If a client’s site suffers latency degradation, SSL expiration, or edge runtime exceptions, alarms notify the engineering team immediately.
• The team resolves issues proactively before the business owner or their customers ever experience a disruption.

---

4. The Business Engine & Capability Expansion Flywheel

Traditional agencies suffer from linear economics: each new client requires proportional maintenance, and bespoke code written for one client remains trapped in an isolated codebase.

SiteSwarm operates as a compounding Capability Flywheel:

flowchart TD
    A["Client A Demands New Bespoke Capability\n(e.g., Dynamic Turnstile Lead Capture)"] --> B["Build & Verify for Client A as Vertical Customization"]
    B --> C["Abstract into Headless Platform Package\n(@siteswarm/capability-*)"]
    C --> D["Register in Central Capability Catalog\n(@siteswarm/governance)"]
    D --> E["Addressable Market (TAM) Expands\nPitch new prospective clients with proven capability"]
    D --> F["Frictionless Fleet Upsell\nBackport to existing clients for low incremental cost"]
    E & F --> G["Compounding Agency Retainer & Expansion Revenue"]
    G --> A

4.1 The Capability Lifecycle

1. Vertical Inception: A feature is initially implemented for a single client in apps/<client>/ and tagged in swarm.config.ts as vertical-custom.
2. Generalization & Extraction: If the feature solves a recurring business problem, it is refactored into a headless, client-agnostic platform package under packages/ (stripping all client-specific branding and layouts).
3. Catalog Registration: The capability contract, configuration options, and SemVer version are registered in SwarmCapabilityRegistry within @siteswarm/governance.
4. Fleet Upsell & Backporting: Coding agents can now backport the capability into existing client applications. The agent declares the capability in apps/<existing-client>/swarm.config.ts, writes bespoke UI matching that client’s unique brand, and runs the evaluation suite.

4.2 Commercial Monetization Framework

SiteSwarm’s commercial model consists of three reinforcing tiers:

1. Initial Onboarding & Setup Fee: Covers discovery, brand asset ingestion, initial application scaffolding, and authoring the bespoke UI.
2. Recurring Base Retainer: Monthly subscription covering Cloudflare edge hosting, synthetic monitoring, SSL certificates, automated accessibility auditing, and access to the client CMS for BAU edits.
3. Modular Capability Upsells: Once a capability exists in the Swarm catalog, it can be unlocked for existing clients as an incremental monthly retainer add-on or flat rollout fee. Because the backend logic is pre-built and typed, the marginal cost to deliver the feature is near zero.

(Note: Concrete pricing tiers and commercial contract structures are defined in commercial strategy documents and remain decoupled from core product requirements.)

---

5. High-Impact Local Business Capabilities & Inquiry Reliability

For local brick-and-mortar businesses, a website is not a vanity brochure; it is an active sales pipeline. The platform must satisfy several core functional product requirements to drive conversions and protect business relationships.

5.1 Customer Inquiry Capture & High-Reliability Lead Delivery

Missing a customer inquiry (a catering request, brake inspection appointment, or emergency plumbing quote) directly results in lost revenue for a local business. Industry data shows that over 70% of local service contracts go to the business that responds first.

Requirements:

• Zero Lost Leads (Durability): Customer form submissions must be durably captured. Temporary upstream network drops or downstream third-party service degradations must never cause a submission to be dropped or lost.
• Instant Business Owner Alerting: When a customer submits an inquiry, the business owner must receive an immediate notification (via SMS text message to their mobile phone and via email) within seconds.
• Frictionless Spam Defense: Forms must be guarded by automated bot detection (e.g. Cloudflare Turnstile) that runs invisibly without forcing human customers to solve frustrating image captchas.
• Tenant Data Isolation & Customer Privacy: Customer leads and contact submissions must be strictly partitioned per business. One client’s inquiries must never be stored in a shared, unpartitioned schema or made accessible to another tenant.

5.2 Trust, Social Proof & Reputation Facilitation

Local consumers place overwhelming weight on peer reviews and ratings before visiting or hiring a local business.

Requirements:

• Verified Review Integration: Sites must have the capability to display verified customer reviews and ratings (e.g. Google Business Profile reviews) directly on the landing page, cached for instant mobile performance.
• Reputation Funnel Facilitation: The platform should support smart post-service feedback workflows that direct highly satisfied customers to public review channels (like Google Maps) while routing constructive feedback directly to the business owner.

5.3 Local Discovery & Structured Data Visibility

Search visibility in the local “Map Pack” and organic search results is a primary organic acquisition channel for brick-and-mortar businesses.

Requirements:

• Strict LocalBusiness Schema.org: Every client application must automatically generate valid, compliant JSON-LD structured data declaring the business type (e.g. Bakery, AutoRepair, Dentist), exact geographical coordinates, street address, telephone, price range, and opening hours specifications.
• Dynamic Hours Synchronization: If holiday hours or emergency closures are updated in the CMS, the structured data must synchronize so search engines do not display outdated hours to prospective customers.

---

6. Client Retention & Ongoing Value Demonstration

6.1 The “Invisible Retainer Paradox” & Churn Prevention

In traditional agencies, frequent maintenance tickets and broken servers remind the client that the agency exists. In SiteSwarm’s high-reliability model, the infrastructure operates silently and flawlessly.

This creates the “Invisible Retainer Paradox”: after 6 to 12 months of zero downtime and zero disruptions, a business owner might forget the active value being provided and wonder why they continue paying a monthly retainer.

6.2 Automated Monthly Client ROI Reporting

To combat churn and continuously prove platform value without requiring engineer time, the platform must proactively demonstrate its ongoing return on investment:

Requirements:

• Automated Delivery: On the first of every month, an automated digest must be generated and emailed directly to the business owner with zero human engineering effort.
• Non-Technical Business Impact Metrics: The report must translate technical stability into tangible business metrics that a small business owner cares about:
  • Inquiries & Leads Captured: Total contact form submissions, quote requests, and click-to-call phone interactions during the month.
  • Visitor Volume: Total local visitors and mobile device percentage.
  • Operational Uptime: Verified 99.9%+ availability confirmation (“Your site was available 100% of the time with zero outages”).
  • Speed & Accessibility Grade: Verified mobile performance score demonstrating that their site loads faster than local competitors.
• Relationship Reinforcement: Proves that the agency is actively safeguarding the business’s digital front door 24/7/365 while the engineer focuses on their day job.

---

7. The Automated Linter & Evaluation Gatekeeper Suite

Because AI coding agents author 100% bespoke UI markup and styling without shared visual components, the CI Evaluation Suite serves as the authoritative quality firewall.

All client applications must pass four mandatory evaluation gates before deployment:

Gate	Focus Area	Standard / Threshold	Failure Action
1. Accessibility Gate	WCAG 2.1 AA Compliance	Zero axe-core or pa11y AA violations (contrast ratios, image alt text, aria semantics, keyboard focus traps).	Blocks CI build; agent must remediate markup.
2. Mobile Performance Budget Gate	Core Web Vitals	Lighthouse Mobile Performance Score >= 95; initial edge JS payload < 50 KB; zero layout shift (CLS < 0.1).	Blocks CI build; flags bloated dependencies or unoptimized assets.
3. Semantic HTML & SEO Gate	Search Engine Visibility & Structure	Strict heading hierarchy (h1 -> h2 -> h3); valid Schema.org JSON-LD structured data for LocalBusiness.	Fails build if structured data is malformed or missing required schema fields.
4. Cloudflare Edge Runtime Gate	Serverless Compatibility & Security	Zero forbidden Node.js built-ins (fs, net, child_process); strict input sanitization on all form endpoints.	Blocks edge bundle generation if non-edge primitives are detected.

---

8. Type-Safe Governance & Agent Developer Experience

To enable AI coding agents to operate autonomously without human micromanagement, every application must declare its configuration in a strongly typed manifest: apps/<appId>/swarm.config.ts.

8.1 Governance Invariants

• Compile-Time Safety: All capability options, versions, and metadata are validated against TypeScript interfaces exported from @siteswarm/governance.
• Target File Integrity: Every path listed in targets: [...] must physically exist on disk. pnpm swarm audit verifies target existence and fails CI if an agent renames or deletes a target without updating the manifest.
• Zero Ghost Verticals: Unregistered bespoke business logic is forbidden. Any one-off client logic must be tagged as vertical-custom with a mandatory human-readable description.

8.2 Agent Scaffolding Velocity & Deterministic Feedback Loops

For AI agents to function effectively within an isolated worktree model:

• Instant Blueprint Scaffolding: Scaffolding a compliant client application skeleton must be fully automated via a single CLI command (e.g. pnpm swarm create <client-name>), setting up typed configs, edge build adapters, and directory targets in seconds.
• Machine-Readable Evaluation Diagnostics: All evaluation gates (typechecker, linter, accessibility scanner, performance budgeter) must provide structured machine-readable error output (e.g. JSON diagnostics specifying exact file, line number, rule violated, and suggested fix). This enables autonomous agents to parse CI feedback and self-heal in a tight loop before requesting human review.

---

9. Client Lifecycle & Operating Protocol

sequenceDiagram
    autonumber
    actor Owner as Local Business Owner
    actor Eng as Daytime Engineer
    actor Agent as AI Coding Agent
    participant CI as CI & Evaluation Suite
    participant Edge as Cloudflare Edge Platform

    Owner->>Eng: Submit brand assets, photography, and business goals via intake
    Eng->>Agent: Prompt agent to scaffold client app and author bespoke UI
    Agent->>Agent: Scaffold app, configure swarm.config.ts, generate bespoke UI
    Agent->>CI: Run local test suite, a11y scanner, and Lighthouse audit
    CI-->>Agent: Self-correct any lint/a11y/performance defects
    Agent->>Edge: Push PR; provision Ephemeral Preview URL
    Eng->>Owner: Share ephemeral preview URL to review on smartphone
    Owner-->>Eng: Review and approve preview
    Eng->>CI: Merge PR to main
    CI->>Edge: Deploy to isolated production edge domain
    CI->>Edge: Activate synthetic health checks & alarms
    Owner->>Edge: Perform BAU content updates via Client CMS independently
    CI->>Owner: Automated monthly ROI impact digest emailed on 1st of month

9.1 Streamlined Client Intake & Digital Asset Onboarding

The initial discovery and asset collection phase is historically the biggest bottleneck in agency workflows:

• Low-Friction Intake: Small business owners must have a simple, non-technical mechanism to submit high-resolution logos, brand color preferences, store hours, staff bios, and photography without navigating complex software or email thread sprawl.
• Automated Asset Normalization: Client-uploaded photography and assets must pass through an automated optimization pipeline that compresses, resizes, and generates modern responsive formats (e.g. WebP/AVIF). This guarantees that client-provided photos never degrade mobile performance budgets or trigger Lighthouse CI failures.

9.2 Velocity Benchmark

• Target Onboarding Turnaround: The end-to-end duration from brand asset intake to an interactive ephemeral preview URL on the business owner’s smartphone should take less than 24 to 48 hours.

---

10. Success Metrics & Key Performance Indicators (KPIs)

Metric Category	Key Performance Indicator (KPI)	Target Value
Daytime Stability	Weekday Daytime Engineering Interventions	0 per week (zero emergency maintenance during work hours).
Accessibility	Automated WCAG 2.1 AA Compliance Violations	0 violations across all production client applications.
Performance	Lighthouse Mobile Performance Score	>= 95 on all primary client landing pages.
Observability	Synthetic Probe Fleet Coverage	100% of active client domains probed every 5 minutes.
Lead Durability	Customer Inquiry Delivery Reliability	100% (zero dropped or lost customer inquiries).
Lead Notification Speed	Inquiry Submission to Owner SMS Alert	< 10 seconds from customer click to owner phone alert.
Client Retention	Automated Monthly ROI Digest Delivery Coverage	100% of active clients receive automated report on 1st of month.
Build & CI Velocity	Path-Filtered CI Pipeline Runtime	< 3 minutes for single-client PR builds.
Client Autonomy	BAU Routine Edits Handled by Engineer	0% (100% of routine content updates self-served via CMS).

---

11. Architectural Deferrals & True Specifications Roadmap

To prevent premature optimization and retain clean separation of concerns, the PRD defines product requirements while explicitly deferring technical execution to dedicated Living True Specifications:

Domain	Specification Document	Scope & Focus	Status
Capability Governance & Manifests	docs/CAPABILITY_MANAGEMENT.md	Authoritative TypeScript contracts (swarm.config.ts), capability catalog, and static audit tooling.	🟢 Active True Spec
High-Level Design & Topology	HIGH_LEVEL_DESIGN.md	Macro-architecture, monorepo topology, build-time vs runtime isolation, and blast-radius boundaries.	🟢 Active Document (Recalibration in #21)
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
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