Local Development Runtime, Multi-Service Binding Emulation, and Offline Velocity Specification

Local Development Runtime, Multi-Service Binding Emulation, and Offline Velocity Specification

Document Status: Living True Specification (Single Source of Truth)
Authority: Core Systems & Infrastructure Architecture
Related Epics: #36 (Local Dev Runtime & Emulation), #34 (Client App Anatomy), #35 (Headless Capability Anatomy), #96 (Multi-Worker Platform Services), #101 (Capability Governance)
Related Documents: HIGH_LEVEL_DESIGN.md, docs/DATA_ISOLATION_AND_STORAGE.md, docs/specs/MULTI_WORKER_PLATFORM_SERVICES.md, docs/CLIENT_CMS.md

---

1. Executive Summary & Design Rationale

SiteSwarm is specifically engineered for software engineers who build, scale, and maintain local business web applications during off-hours (evenings, weekends, on laptops, and occasionally while traveling offline).

If local development requires active internet connectivity, remote Cloudflare credentials, live API tokens, or remote deployments just to test a UI change or submit a contact inquiry, developer velocity drops to zero. Furthermore, when multiple autonomous AI agents work in parallel across isolated Git worktrees (wt), hardcoded ports and rigid cloud dependencies cause catastrophic collisions.

flowchart TD
    subgraph DeveloperEnvironment["Offline Local Developer Environment (Zero Cloud Credentials)"]
        direction TB
        DevRunner["Fleet Dev Runner (scripts/dev-runner.ts)\n• Dynamic Port Allocation (OS Kernel Discovery)\n• Collision-Free Parallel Worktrees\n• Injects SITESWARM_PORT_* & .swarm/ports.json"]

        subgraph ClientApps["Client Applications (apps/*)"]
            Bakery["apps/bakery\n(Astro + Miniflare platformProxy)"]
            AutoRepair["apps/auto-repair\n(Astro Static-First)"]
            Agency["apps/software-agency\n(Astro Static-First)"]
            Docs["apps/docs\n(Starlight Docs)"]
        end

        subgraph LocalD1["Local Storage & State (.wrangler/state/v3/d1)"]
            BakeryD1["green-leaf-bakery-d1\n(Local SQLite Replay)"]
            Fixtures["Deterministic Fixtures\n(schema.sql + seed.sql)"]
        end

        subgraph ServiceEmulation["Multi-Service Binding Mesh (Miniflare / Local Wrangler)"]
            MockLeads["env.LEADS_SERVICE\n(Turnstile Test Key: 1x00...AA)"]
            MockCMS["env.CMS_SERVICE\n(Local Fallback Store)"]
        end
    end

    DevRunner --> ClientApps
    Bakery --> BakeryD1
    BakeryD1 --> Fixtures
    ClientApps --> ServiceEmulation

The Three Foundational Local DX Invariants:

1. The Offline Development Invariant: Running pnpm dev must boot the entire client application and all capability bindings locally without an internet connection or Cloudflare account credentials.
2. The Zero-Collision Worktree Invariant: Multiple developers or parallel AI agents executing in separate worktrees (wt) must never fail due to EADDRINUSE port collisions. Port allocation must negotiate dynamically with the host kernel.
3. The Deterministic Reset Invariant: Database state must be instantly erasable and reconstitutable via pnpm swarm db reset (or pnpm db:reset), restoring deterministic fixtures in under 3 seconds.

---

2. Multi-Service & Binding Emulation Architecture

In production, SiteSwarm client applications run as static edge workers communicating with domain-partitioned platform microservices via Cloudflare Service Bindings (MULTI_WORKER_PLATFORM_SERVICES.md). Locally, this mesh is simulated using a Multi-Process Wrangler Mesh powered by Miniflare.

sequenceDiagram
    autonumber
    actor Dev as Developer / AI Agent
    participant Astro as Client Worker (Astro Dev)
    participant PlatformProxy as @astrojs/cloudflare (Miniflare)
    participant LocalD1 as Local SQLite (.wrangler/state)
    participant ServiceMesh as Local Service Binding Mesh

    Dev->>Astro: pnpm dev (or pnpm dev:bakery)
    Astro->>PlatformProxy: Initialize platformProxy (getPlatformProxy)
    PlatformProxy->>LocalD1: Attach local D1 SQLite database
    Astro->>Dev: Listening on dynamically allocated port (e.g. 4321)

    Dev->>Astro: POST /api/submit-inquiry
    alt Direct D1 Access (Tier 2 Dedicated Storage)
        Astro->>LocalD1: env.DB.prepare(...).run()
        LocalD1-->>Astro: Local SQLite Result
    else Platform Service Binding (Tier 1 Shared Storage)
        Astro->>ServiceMesh: env.LEADS_SERVICE.fetch(req, { headers: { 'X-SiteSwarm-Tenant-Id': appId } })
        ServiceMesh-->>Astro: Emulated 200 OK + Lead Id
    end
    Astro-->>Dev: HTTP 200 OK Response

2.1 Emulation Mechanics: Astro platformProxy & Miniflare

Client applications configure @astrojs/cloudflare in astro.config.mjs:

astro.config.mjs

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  output: "static",
  adapter: cloudflare({
    imageService: "passthrough",
    // Automatically provisions Miniflare bindings in dev for D1, KV, and Service Bindings
    platformProxy: {
      enabled: true,
    },
  }),
});

When astro dev runs, @astrojs/cloudflare initializes Miniflare under the hood, parsing wrangler.jsonc and mapping declared bindings directly to local disk state in .wrangler/state/v3/.

2.2 Cross-Worker Service Binding Patterns

Platform services (services/leads-service, services/cms-service) are bound via wrangler.jsonc:

// apps/<client>/wrangler.jsonc
{
  "name": "siteswarm-app-bakery",
  "compatibility_date": "2026-09-29",
  "compatibility_flags": ["nodejs_compat"],
  "services": [
    { "binding": "LEADS_SERVICE", "service": "siteswarm-leads-service" },
    { "binding": "CMS_SERVICE", "service": "siteswarm-cms-service" }
  ]
}

Locally, cross-service calls resolve through two complementary execution patterns:

1. Multi-Worker Wrangler Mesh: Separate wrangler dev processes running concurrently communicate over localhost loopback or Miniflare’s in-memory inter-isolate bridge.
2. In-Process Graceful Fallback (@siteswarm/sdk): When running an individual application in isolation without starting the entire platform fleet, the @siteswarm/sdk client activates fallback mocks that validate schemas, emit development log receipts, and return mock success payloads with zero network dependencies.

---

3. Dynamic Port Allocation & Collision-Free Swarms

A critical bottleneck in parallel agent development is port exhaustion and port collisions (EADDRINUSE). When multiple AI subagents work simultaneously across git worktrees (e.g., one agent fixing Bakery, another refactoring Auto Repair, a third testing CMS migrations), static port assignments break down immediately.

3.1 Kernel-Negotiated Dynamic Port Allocation

SiteSwarm implements kernel-negotiated port discovery in scripts/dev-runner.ts:

scripts/dev-runner.ts

export async function getAvailablePort(preferredPort?: number): Promise<number> {
  return new Promise((resolve, reject) => {
    if (preferredPort && preferredPort > 0) {
      const tester = net.createServer();
      tester.unref();
      tester.once("error", (err: any) => {
        if (err.code === "EADDRINUSE" || err.code === "EACCES") {
          // Port busy: dynamically allocate an ephemeral port from the OS kernel
          getEphemeralPort().then(resolve, reject);
        } else {
          reject(err);
        }
      });
      tester.once("listening", () => {
        const port = (tester.address() as net.AddressInfo).port;
        tester.close(() => resolve(port));
      });
      tester.listen(preferredPort, "127.0.0.1");
    } else {
      getEphemeralPort().then(resolve, reject);
    }
  });
}

3.2 Ephemeral Port Registry (.swarm/ports.json)

Upon startup, the dev orchestrator writes an ephemeral, git-ignored discovery manifest at .swarm/ports.json:

{
  "allocatedAt": "2026-10-01T16:45:00.000Z",
  "pid": 84210,
  "apps": {
    "bakery": {
      "name": "bakery",
      "appId": "@siteswarm/app-bakery",
      "port": 4321,
      "url": "http://localhost:4321"
    },
    "auto-repair": {
      "name": "auto-repair",
      "appId": "@siteswarm/app-auto-repair",
      "port": 4322,
      "url": "http://localhost:4322"
    }
  }
}

In addition, each child process receives injected environment variables:

• PORT=<allocated_port>
• PUBLIC_SITE_URL=http://localhost:<allocated_port>
• SITESWARM_PORT_BAKERY=<port>
• SITESWARM_PORT_AUTO_REPAIR=<port>
• SITESWARM_PORTS_MANIFEST=.swarm/ports.json

This ensures full cross-service discovery without hardcoding network addresses.

---

4. Local Database Seeding & Deterministic Reset Workflows

To ensure zero-friction testing and rapid reproduction of bugs, database fixtures are deterministic, versioned, and easily reset.

4.1 Schema vs. Seed Separation

Each application or capability package maintains two distinct SQL files:

1. schema.sql: Pure Data Definition Language (DDL) containing CREATE TABLE IF NOT EXISTS and index statements.
2. seed.sql: Data Manipulation Language (DML) containing deterministic seed rows and initial fixtures using INSERT OR REPLACE INTO.

4.2 Database Commands

Developers and agents have access to instant database commands at both workspace and monorepo levels:

Command	Scope	Action
pnpm swarm db reset	Monorepo Fleet	Deletes local SQLite state (.wrangler/state/v3/d1), runs schema.sql, and replays seed.sql across all databases.
pnpm swarm db reset --app bakery	Single App	Resets only the targeted application’s D1 database.
pnpm swarm db migrate	Monorepo Fleet	Executes schema.sql against all local databases without wiping existing data.
pnpm swarm db seed	Monorepo Fleet	Executes seed.sql to populate or update deterministic test fixtures.
pnpm --filter=@siteswarm/app-bakery run db:reset	Workspace Script	Direct application-level alias using wrangler d1 execute <db> --local.

---

5. Configuration, Secrets Ergonomics & Zero-Leakage Guardrails

SiteSwarm adheres to a strict Zero-Leakage Security Posture. Local test credentials and mock secrets must never be committed to git history or touch production systems.

5.1 Standardized Configuration Hierarchy

Every repository workspace provides template files for local configuration:

• Root .env.example: Monorepo-level environment toggles (SITESWARM_OFFLINE=true, SITESWARM_ENV=development).
• Root & Workspace .dev.vars.example: Cloudflare Workers local secret templates consumed by Wrangler in dev mode.

5.2 Safe Cloudflare Turnstile Test Secret

For local form verification without network access to challenges.cloudflare.com, SiteSwarm uses Cloudflare’s official dummy Turnstile secret key:

TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA

This test key always returns a passing verification result, allowing offline form submission testing.

5.3 Automated Zero-Leakage AST Linter (sec/zero-leakage-guardrails)

Wired directly into pnpm swarm audit and pnpm swarm lint, the linter enforces:

1. Gitignore Protection: Verifies that root .gitignore contains strict exclusion patterns:
   • .env, .env.*, with whitelist !.env.example
   • .dev.vars, .dev.vars.*, with whitelist !.dev.vars.example
   • .swarm/ ephemeral runtime directory
2. Git Index Inspection: Asserts that git ls-files tracks zero .env or .dev.vars files.
3. Template Secret Sanitization: Scans all .env.example and .dev.vars.example files using regular expressions to flag live API tokens (e.g. live Stripe sk_live_*, GitHub PATs ghp_*, AWS Access Keys AKIA*).

---

6. The Offline Development Loop & Verification Protocol

When an engineer or AI agent begins working on SiteSwarm, they can verify their local development environment with this simple protocol:

# 1. Clone & install dependencies
git clone https://github.com/jacobmiller22/siteswarm.git
cd siteswarm
pnpm install

# 2. Initialize local database fixtures (offline)
pnpm swarm db reset

# 3. Verify monorepo architectural integrity & secrets guardrails
pnpm swarm audit

# 4. Launch the concurrent fleet runner (dynamic ports)
pnpm dev
# Or target a single app:
pnpm dev bakery

Verification Checklist:

• Application compiles and serves HTML locally without active internet connectivity.
• D1 queries return deterministic fixtures from .wrangler/state/v3/d1.
• Contact and inquiry forms submit successfully using Turnstile test credentials.
• Concurrent processes across different git worktrees run without port collisions.
• pnpm run check and pnpm test pass with 100% success.