Engineering Spike Report: Software Agency Scaffolding & Multi-Tenant Aesthetic Divergence

Engineering Spike Report: Software Agency Scaffolding & Multi-Tenant Aesthetic Divergence

Spike Reference: Issue #42
Parent Epic: Issue #39 (epic(spike): client emulation harness and capability reuse stress test)
Author: Antigravity Technical Lead
Target Date: 2026-09-29
Status: 🟢 Completed & Verified

---

1. Executive Summary

This engineering spike evaluates the authoring velocity, architectural independence, and multi-tenant ergonomics of the SiteSwarm platform by instantiating the second prototype client application: Apex Labs (apps/software-agency), a distributed systems and cloud edge engineering agency.

In contrast to Client App 1 (Green Leaf Bakery, apps/bakery), which embodies an artisan, warm, wood-fired culinary aesthetic (#FAF7F2, #2D5A27, Fraunces serif typography), Apex Labs features a sleek, high-tech, minimalist aesthetic with obsidian dark-mode surfaces, electric cyan and royal blue accents (#0A0D12, #00E5FF, #3B82F6), and monospace/grotesk typography (Space Grotesk + JetBrains Mono).

Key Deliverables & Achievements

1. 100% Bespoke Client Application: Scaffolded clean Astro 7 + @astrojs/cloudflare application in apps/software-agency with zero shared UI components or CSS classes from the bakery application.
2. 5 Bespoke Informational Pages:
   • /: Tech hero with live V8 isolate code preview terminal, SLA telemetry metrics (99.999% SLA, < 14ms P99), capabilities preview, case studies preview, engineering axioms, and embedded consultation intake.
   • /services: Deep dive into 6 technical specializations (Edge Worker Topologies, AI Agent Fleets, Distributed SQLite WAL, Cloud Monolith De-Migrations, High-Throughput Streams, Compile-Time AST Governance) and the 4-phase delivery protocol.
   • /work: 3 detailed enterprise case studies (StrataPay Global, Nexus Infrastructure, AeroSensor Systems) with audited before-and-after empirical telemetry comparison matrix.
   • /about: Systems engineering pedigree, leadership bios (Elena Vance Ph.D., Marcus Sterling, Dr. Soren Hayes), and 4 core engineering axioms.
   • /contact: Direct engineering intake consultation form with antispam honeypot guard, 24-hour turnaround SLA, and technical FAQs.
3. Edge API Route: Implemented POST /api/submit-inquiry and GET /api/submit-inquiry with corporate email validation, minimum payload constraints, and silent bot honeypot trap.
4. Compile-Time Governance Contract: Authored apps/software-agency/swarm.config.ts conforming strictly to @siteswarm/governance contracts, declaring lead-capture, dynamic-seo, and synthetic-alarms capabilities.
5. Playwright E2E Test Suite: Authored 18 functional tests in apps/software-agency/e2e/ validating computed CSS tokens, JSON-LD schema, navigation transitions, lead capture form lifecycle, and edge API contracts.
6. Full Monorepo Verification: 40 total Playwright functional tests passing across both applications (22 bakery + 18 agency) in under 6 seconds.

---

2. Aesthetic & Architectural Divergence Matrix

The core objective of the Client Emulation Harness (Issue #39) is proving that SiteSwarm does not generate cookie-cutter templates. The table below demonstrates the total divergence between the two client applications:

Architectural Vector	Client App 1: Green Leaf Bakery (apps/bakery)	Client App 2: Apex Labs (apps/software-agency)
Domain Sector	Artisan Bakery, Sourdough Hearth & Catering	Distributed Systems & Cloud Edge Consultancy
Visual Tone	Warm, organic, tactile, craft culinary	Cold, obsidian, high-velocity, precision tech
Background Base	#FAF7F2 (Warm Vanilla / Cream)	#0A0D12 (Deep Space Obsidian)
Primary Accent	#2D5A27 (Forest Hearth Green)	#00E5FF (Electric Neon Cyan)
Secondary Accent	#D4A373 (Golden Crust Ochre)	#3B82F6 (Electric Royal Blue)
Heading Font	'Fraunces', serif (700 weight)	'Space Grotesk', sans-serif (700–800 weight)
Body & Code Font	'Plus Jakarta Sans', sans-serif	'JetBrains Mono', monospace
Key Visual Motif	Sourdough fermentation pills & flour badges	V8 isolate code preview terminal & status tickers
Target Persona	Local neighborhood foodies & catering clients	CTOs, VP of Engineering, Principal Architects
Storage Isolation	Dedicated D1 SQLite Database (DB)	Static-only with edge RPC & Cloudflare Workers
Structured Data	schema.org/Bakery (Restaurant)	schema.org/ProfessionalService (LocalBusiness)
Port Allocation	http://localhost:4321	http://localhost:4322

---

3. Governance Configuration (swarm.config.ts)

Conforming to docs/CAPABILITY_MANAGEMENT.md, Apex Labs declares its capabilities and static storage requirements at compile time:

apps/software-agency/swarm.config.ts

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

export default defineAppConfig({
  appId: "software-agency",
  name: "Apex Labs",
  brand: {
    primaryColor: "#00E5FF",
    accentColor: "#3B82F6",
    fontFamilyHeading: "'Space Grotesk', sans-serif",
    fontFamilyBody: "'Space Grotesk', sans-serif",
    logoAssetPath: "public/assets/logo.svg",
  },
  deployment: {
    productionDomain: "apexlabs.dev",
    stagingDomain: "staging.apexlabs.siteswarm.dev",
    cloudPlatform: "cloudflare",
  },
  capabilities: {
    "lead-capture": {
      type: "horizontal",
      version: "1.2.0",
      targets: [
        "src/components/ContactForm.astro",
        "src/pages/api/submit-inquiry.ts",
      ],
      options: {
        provider: "turnstile",
        notifyChannel: "webhook",
        storeSubmissions: false,
      },
      storage: {
        mode: "static-only",
      },
    },
    "dynamic-seo": {
      type: "horizontal",
      version: "1.4.0",
      targets: ["src/layouts/BaseLayout.astro"],
      options: {
        schemaType: "LocalBusiness",
        enableBreadcrumbs: true,
        generateOpenGraphImages: true,
      },
      storage: {
        mode: "static-only",
      },
    },
    "synthetic-alarms": {
      type: "horizontal",
      version: "1.0.0",
      targets: ["src/pages/api/submit-inquiry.ts"],
      options: {
        probeIntervalMinutes: 5,
        alertWebhookEnvVar: "PAGERDUTY_WEBHOOK_URL",
        assertStatusCode: 200,
      },
      storage: {
        mode: "static-only",
      },
    },
  },
});

---

4. Verification & Testing Rigor

To prevent shallow or cosmetic verification, four distinct Playwright functional test suites were authored for Apex Labs:

1. e2e/home.spec.ts (6 tests):
   • Validates HTTP 200, meta tags, and ProfessionalService JSON-LD structured data.
   • Computes live CSS properties on the DOM: verifies #0A0D12 (rgb(10, 13, 18)) background, #F8FAFC text, Space Grotesk heading font, and JetBrains Mono code tokens.
   • Validates hero live terminal preview, status dot pulse, telemetry metrics strip, and technical footer.
2. e2e/navigation.spec.ts (3 tests):
   • Validates seamless client navigation across all 5 routes (/, /services, /work, /about, /contact).
   • Asserts active nav state styling (.nav-item.active), full rendering of all 6 capabilities cards, 4 engagement steps, 4 benchmark rows, and 3 leadership bios.
3. e2e/contact-form.spec.ts (3 tests):
   • Submits valid technical specifications, asserting loading states, response handling, generated APX- inquiry IDs, and automatic form resets.
   • Simulates automated bot traffic against hidden honeypot input (#company_website_url) to verify bot mitigation.
4. e2e/api.spec.ts (6 tests):
   • Directly tests edge route POST /api/submit-inquiry and GET /api/submit-inquiry.
   • Validates 422 HTTP error contracts on missing names, malformed email addresses, and truncated specifications.

Monorepo Test Execution Benchmark

Scope: 3 of 4 workspace projects
apps/bakery test:e2e:          22 passed (2.7s)
apps/software-agency test:e2e: 18 passed (2.1s)
Total:                         40 passed (4.8s)

---

5. Authoring Velocity & Agent Ergonomics

Velocity Comparison

• Client App 1 (Bakery): Required foundational monorepo setup, Cloudflare D1 SQL schema definition, mobile BAU quick-pad UX, and full artisan component library.
• Client App 2 (Apex Labs): Completed in a single working session. By leveraging Astro 7’s clean component model and @siteswarm/governance contracts, an agent can scaffold 5 bespoke pages, edge API routes, and 18 high-confidence Playwright tests in under 20 minutes of clock time.

Insights & Lessons Learned

1. Parallel WebServer Execution: Spawning multiple Astro preview servers during pnpm -r test:e2e can trigger port collisions or race conditions when inspecting background server state. Specifying --workspace-concurrency=1 at the monorepo root ensures deterministic, serial test runs across workspace projects without performance degradation.
2. CSS Background Shorthand Gotcha: Modern Playwright tests checking toHaveCSS("background-color") on elements styled with background: linear-gradient(...) will receive rgba(0, 0, 0, 0) because gradient fills are evaluated as background-image. Tests should assert against background-image using regex matching.
3. Zero Leaked State: By strictly assigning port 4321 to Bakery and 4322 to Apex Labs in their respective playwright.config.ts, both preview servers can run without collision even when operated concurrently.