Skip to content
SiteSwarm Docs

Client App 1 (Green Leaf Bakery) Scaffolding & Ergonomics Spike Report

Client App 1 (Green Leaf Bakery) Scaffolding & Ergonomics Spike Report

Section titled “Client App 1 (Green Leaf Bakery) Scaffolding & Ergonomics Spike Report”
  • Issue: #40 — spike(app): scaffold client app 1 (bakery) with bespoke aesthetic and core structure
  • Parent Sub-Epic: #39 — epic(spike): client emulation harness and capability reuse stress test
  • Application Target: apps/bakery (@siteswarm/app-bakery)
  • Governance Manifest: apps/bakery/swarm.config.ts
  • Date: 2026-09-29

1. Executive Summary

Section titled “1. Executive Summary”

As the first prototype client application in the SiteSwarm Client Emulation Harness (#39), Green Leaf Bakery (apps/bakery) demonstrates SiteSwarm’s core thesis: 100% bespoke visual presentation paired with shared, headless platform capabilities.

We bootstrapped a pnpm monorepo workspace from an empty root, authored the foundational @siteswarm/governance TypeScript contracts matching docs/CAPABILITY_MANAGEMENT.md and docs/DATA_ISOLATION_AND_STORAGE.md, and scaffolded a complete, production-grade Astro web application with an earthy artisan visual identity, schema.org dynamic SEO, interactive menu catalog, and edge API endpoints.

2. Velocity & Build Ergonomics Telemetry

Section titled “2. Velocity & Build Ergonomics Telemetry”
Metric Measured Value Architectural Assessment
Workspace Cold Bootstrap 2.1s Fast pnpm workspace resolution across apps/* and packages/*.
Astro SSG Prerender Time 216ms Instant prerendering of static pages (/, /menu, /about, /contact).
Cloudflare Server Build Time 452ms Total edge worker compilation bundle generation.
Typecheck Time (check) 1.8s Zero errors, zero warnings, zero hints across 23 files (tsc + astro check).
Playwright Functional Tests 3.6s (17/17 passed) Comprehensive verification of CSS styling delivery, computed tokens, interactive filtering, and form submission flows on built preview environment.
Shared Visual UI Bleed 0% 100% bespoke styles, zero global UI component coupling.

3. Boilerplate Friction Points & Root-Cause Solutions

Section titled “3. Boilerplate Friction Points & Root-Cause Solutions”

During the initial scaffolding spike, three distinct friction points were encountered and resolved. These findings directly inform the Automated Intake & Scaffolding Blueprint (#37) and Client App Anatomy (#34).

Friction 1: pnpm v12 Supply Chain Build Script Security Gate (ERR_PNPM_IGNORED_BUILDS)

Section titled “Friction 1: pnpm v12 Supply Chain Build Script Security Gate (ERR_PNPM_IGNORED_BUILDS)”
  • Observation: When installing Astro and native platform packages (esbuild, sharp, workerd), pnpm v12 halted installation with ERR_PNPM_IGNORED_BUILDS. In modern pnpm, the legacy pnpm.onlyBuiltDependencies field in package.json is ignored.
  • Root Cause: pnpm v12 moves build script authorization to pnpm-workspace.yaml under allowBuilds.
  • Solution Applied: Configured root pnpm-workspace.yaml: 
    packages:
      - 'apps/*'
      - 'packages/*'
    

    allowBuilds:
      esbuild: true
      sharp: true
      workerd: true
  • Platform Recommendation for #37: The scaffolding generator must automatically ensure allowBuilds includes necessary native binaries in pnpm-workspace.yaml.

Friction 2: Adapter & Modern Astro Version Alignment

Section titled “Friction 2: Adapter & Modern Astro Version Alignment”
  • Observation: An initial attempt to pair @astrojs/cloudflare with an older Astro 5 pin failed with Package subpath './app/manifest' is not defined by "exports" in astro/package.json.
  • Root Cause: @astrojs/cloudflare@14.x targets modern Astro (v7+), which modularized internal server manifests into ./app/manifest.
  • Solution Applied: Aligned workspace dependencies to modern Astro (^7.3.5) and @astrojs/cloudflare (^14.3.3), producing a seamless build in 844ms.
  • Platform Recommendation for #34: Maintain synchronized lockstep versions of Astro core and platform adapters within the repository root or a shared catalog.

Friction 3: Static Pre-rendering with Dynamic Edge Endpoints

Section titled “Friction 3: Static Pre-rendering with Dynamic Edge Endpoints”
  • Observation: Client websites require pure static performance (100/100 Lighthouse) for content pages (/, /menu), but also require serverless execution for form inquiries (/api/submit-inquiry) and webhook relays (/api/catering-pos-relay).
  • Solution Applied: Configured output: "static" in astro.config.mjs combined with @astrojs/cloudflare({ imageService: "passthrough" }). Static pages are prerendered at build time, while API routes declare export const prerender = false;, routing on-demand requests through Cloudflare Workers.

4. Bespoke Visual Identity Deliverables

Section titled “4. Bespoke Visual Identity Deliverables”

In accordance with SiteSwarm’s core tenets, apps/bakery does not consume any generic theme tokens or shared button/card wrappers:

  1. Brand Identity & Earthy Palette:
    • Primary: #2D5A27 (Deep forest artisan green)
    • Accent: #D4A373 (Warm toasted loaf amber)
    • Backgrounds: #FAF7F2 (Stone-ground flour cream) and #F3ECE1 (Warm timber)
    • Typography: Fraunces (warm, character-rich serif headlines) and Plus Jakarta Sans (clean modern body)
  2. Homepage (src/pages/index.astro):
    • Hero with storytelling: 48-hour wild fermentation, heirloom Willamette grains, wood-fired stone hearth.
    • Handcrafted SVG artisan country boule with scoring ear and blistered crust.
    • Daily bake fresh schedule callouts (6:30 AM, 8:30 AM, 11:00 AM).
  3. Menu Catalog (src/pages/menu.astro & src/components/PastryGrid.astro):
    • 8 bespoke bakes spanning Artisan Breads, Morning Viennoiserie, and Seasonal Tarts.
    • Grain provenance details (e.g., Organic Hard Red Winter Wheat, Rogue Valley Rye, Sel Gris).
    • Dietary tags (100% Sourdough, Naturally Vegan, Ancient Grain).
  4. Hours & Location (src/components/HoursAndLocation.astro):
    • Physical address in Portland’s historic Eastside Arts Quarter.
    • Weekly hearth schedule and oven pull times.
    • Transit, parking, and customer directions.
  5. Contact & Catering (src/pages/contact.astro & src/components/ContactForm.astro):
    • Full catering and special order intake.
    • Antispam honeypot and Turnstile security placeholder.
    • Catering policies FAQ (48-hour feeding notice, Portland courier delivery).

5. Governance Manifest Compliance (apps/bakery/swarm.config.ts)

Section titled “5. Governance Manifest Compliance (apps/bakery/swarm.config.ts)”

The application’s manifest was authored using @siteswarm/governance contracts and verified against disk targets:

Capability Name Type Target Files on Disk Verification Status
lead-capture horizontal src/components/ContactForm.astro, src/pages/api/submit-inquiry.ts 🟢 Target files exist; validated
menu-catalog horizontal src/pages/menu.astro, src/components/PastryGrid.astro 🟢 Target files exist; validated
dynamic-seo horizontal src/layouts/BaseLayout.astro 🟢 Target files exist; JSON-LD rendered
legacy-pos-sync vertical-custom src/pages/api/catering-pos-relay.ts 🟢 Target files exist; stub validated

6. Functional Playwright Testing on Built Preview Environment

Section titled “6. Functional Playwright Testing on Built Preview Environment”

To guarantee that the application renders cleanly in production with active CSS styling, interactive components, and edge endpoints, we established a Playwright functional test harness (apps/bakery/e2e/):

  1. Production Built Environment Execution: Tests execute against the compiled Cloudflare preview server (astro preview --port 4321) rather than an in-memory dev server, guaranteeing zero build/runtime surprises.
  2. Visual & Styling Assurance:
    • Asserts computed background color matches warm cream design tokens (rgb(250, 247, 242)).
    • Asserts typography font family resolves to Fraunces serif headlines.
    • Asserts button colors, border radii, and visual hierarchies.
    • Asserts SVG hero loaf artwork rendering with bounding box dimensions >150x100px.
  3. Interactive Behavioral Flows:
    • Menu Category Filtering: Verifies clicking “Morning Pastries” dynamically displays only viennoiserie and hides bread/tart cards; returning to “All” restores all 8 items.
    • Catering Form Submission: Fills and submits an event inquiry, verifies submission transition, edge API handler response, reset of input fields, and success alert banner.
    • Security & Honeypot: Verifies Turnstile security container and asserts bot honeypot input is hidden from legitimate users.
    • Edge API Verification: Tests GET and POST handlers for /api/submit-inquiry and /api/catering-pos-relay.
  4. Automated CI Integration (.github/workflows/ci.yml):
    • Formulates a GitHub Actions workflow running on pull request and push to main.
    • Gatekeepers: Typecheck (pnpm run check), build (pnpm run build), and headless Chromium Playwright test execution (pnpm run test:e2e).

7. Next Steps in Sub-Epic #39

Section titled “7. Next Steps in Sub-Epic #39”
  1. Issue #41 (spike(cms): integrate EmDash / mobile BAU content management into bakery app): Connect PastryGrid and HoursAndLocation to Cloudflare D1 / EmDash mobile editing so the bakery owner can toggle sold-out pastries and post emergency alerts from their smartphone.
  2. Issue #42 (spike(app): scaffold client app 2 (software company) informational web presence): Scaffold contrasting client app with high-tech, minimalist visual identity and zero shared UI with the bakery.