Skip to content
SiteSwarm Platform Documentation

Prd

SiteSwarm — Product Requirements Document (PRD)

1. Executive Summary & Strategic Objective

SiteSwarm is an agent-first software engineering platform designed to deliver bespoke, high-performance web applications for local small businesses while maintaining near-zero ongoing operational overhead.

1.1 The Market Problem

Local businesses are underserved by two extremes:

  1. Generic Website Builders: Deliver cookie-cutter templates that suffer from slow mobile performance and rigid customization limits.
  2. Traditional Web Agencies: Charge high upfront build fees and expensive monthly retainers due to manual, non-compounding engineering workflows.

SiteSwarm bridges this gap by combining 100% bespoke visual frontend design (VISUAL_FREEDOM_AND_SHARED_CORE.md) with a shared monorepo backbone where headless capabilities, edge infrastructure, and automated quality gates compound across the entire client fleet.

1.2 The Dual-Engine Operating Thesis

SiteSwarm is built for engineers who maintain demanding daytime careers while scaling a local software agency during off-hours:

  • Daytime Zero-Anxiety Operation: Serverless edge hosting (Cloudflare Workers), self-service client CMS editing for routine updates, and proactive health monitoring ensure zero daytime engineering interruptions.
  • Off-Hours High-Velocity Delivery: Living application blueprints, headless platform capabilities, and automated verification gates enable rapid client onboarding and bespoke UI iteration.

2. Core Target Personas

  1. The Daytime Engineer / Agency Operator: Needs zero operational toil during work hours, rapid scaffolding velocity during off-hours, and automated quality gates that verify accessibility, performance, and edge safety before review.
  2. The Local Business Owner: Needs a distinct digital storefront that loads instantly on mobile devices, reliably captures customer inquiries, and allows effortless 60-second smartphone updates for hours, specials, and emergency notices without waiting on a developer.

3. Foundational Product Principles

3.1 Storefront Visual Freedom + Battle-Hardened Shared Functionality

SiteSwarm rejects shared storefront view templates across clients:

  • Visual Freedom: Every client application in apps/<client>/ receives bespoke HTML/Astro markup, typography, and CSS tailored to its authentic brand identity (VISUAL_FREEDOM_AND_SHARED_CORE.md).
  • Battle-Hardened Shared Functionality: Shared capabilities provide tested domain logic, calculation engines, and edge integrations (app-hosted or platform-hosted), while bespoke client requirements are cataloged as custom capabilities for future cross-fleet rationalization (CAPABILITY_MANAGEMENT.md).
  • Automated Quality Firewall: Instead of constraining design through rigid templates, SiteSwarm enforces quality through automated CI gates (WCAG 2.1 AA accessibility, mobile performance budgets, Schema.org structured data, and edge runtime compatibility).

3.2 Mandatory Self-Service Client CMS for Routine Updates

Business owners must never depend on an engineer to post a “Sold Out” notice, update holiday hours, or announce an inclement weather closure. Every client application requiring routine operational updates provides an app-hosted, mobile-friendly CMS interface that propagates changes to the live edge site in seconds without requiring a Git commit or CI rebuild (APP_SERVING_CACHE.md).

3.3 Runtime Isolation with Build-Time Leverage

  • Monolithic at Build Time: A single repository consolidates CI pipelines, linters, and capability packages.
  • Isolated at Runtime: Every client application deploys as an independent Cloudflare Worker with isolated data boundaries (DATA_STORAGE_PATTERN.md) so a traffic spike or fault in one client never impacts another.

4. Core Local Business Value Pillars

  1. High-Reliability Inquiry Capture: Durable inquiry intake with invisible bot protection (Cloudflare Turnstile), strict tenant data isolation, and instant business owner notifications.
  2. Local Search & Structured Data Visibility: Automated LocalBusiness Schema.org JSON-LD generation synchronized with business operating hours and metadata.
  3. In-Situ Visual Critique & Review: Interactive preview links with pinned visual critiques (@siteswarm/critique) that persist across deployments until resolved.
  4. Ongoing Value Visibility: Automated operational health and inquiry summaries that demonstrate continuous platform value to business owners.