Architecture Overview

This document outlines the high-level architecture of the Ethotechnics site, including the build process, content structure, and the Cloudflare Workers runtime.

System Overview

Astro packages the site for Cloudflare’s edge network, pulling content and site config data directly during the build. Static assets are served from the Worker assets binding, while Astro edge routes call shared Worker handlers for dynamic behaviors like lead capture and social cards.

graph TD
    User[User] -->|Request| Edge[Cloudflare Worker]

    subgraph "Build Time"
        Content[Content app/src/content/pages/**/*] -->|content layer| Dist[app/dist static assets]
        SiteConfig[Site config app/src/content/site.json] -->|content layer| Dist
        Styles[Styles app/src/styles (styles.css)] -->|astro build| Dist
    end

    subgraph "Runtime"
        Edge -->|Static Asset| Dist
        Edge -->|API Request| AstroRoutes[Astro edge routes]
        AstroRoutes -->|Business Logic| Handlers[Worker handlers/services]
        Handlers -->|Library Feed| Ext[External APIs]
        Handlers -->|Lead Capture| KV[KV / Webhook]
    end

Build Process

bun run build is the single entrypoint for creating deployable artifacts:

1. astro build – Produces the optimized site in app/dist, including any Astro edge routes compiled for Cloudflare Workers.
2. worker bundle build – Compiles the Worker TypeScript into dist/worker so API handlers stay type-checked.
3. astro sitemap integration – Emits app/dist/sitemap.xml from the built output.

Artifacts in app/dist are what the Worker serves via the assets binding defined in wrangler.toml.

Worker Request Flow

The Cloudflare Worker (worker/) is modularized to handle different types of requests efficiently and mirrors the adapters in framework/ for edge functions.

sequenceDiagram
    participant Client
    participant Worker
    participant AstroRoute
    participant Handler
    participant AssetStore

    Client->>Worker: Request (GET /about/)

    alt API Request
        Worker->>AstroRoute: Match edge route (app/src/pages/api/**)
        AstroRoute->>Handler: Execute API handler
        Handler-->>Worker: JSON Response
    else Static Asset
        Worker->>AssetStore: Fetch asset (ASSETS binding)
        alt Found
            AssetStore-->>Worker: Asset Response
        else Not Found
            Worker->>Worker: Check fallback
            Worker-->>Client: 404 / fallback
        end
    end

    Worker-->>Client: Final Response

Local Development

• Preview with hot reload: bun run dev starts Astro’s dev server.
• Exercise Worker bindings: bun run dev:worker (after a bun run build so app/dist exists) runs bunx wrangler dev with the same asset bundle used in production.
• Full check: bun run verify runs linting, builds the site, and executes smoke + Playwright tests.

Directory Structure

• /app: Astro project (layouts, components, and build output in app/dist).
  • src/content/: Content collections for pages and the site config.
  • src/styles/: CSS source bundled through styles.css.
• /partials: Reusable HTML components (header, footer, cards).
• /assets: Client JavaScript modules, icons, and bundled assets.
• /scripts: Build and utility scripts shared by Astro and Worker adapters.
• /worker: Cloudflare Worker source code.
  • handlers/: Request handlers for specific routes.
  • services/: Business logic (Library, Leads).
  • utils/: Shared utilities.
• /framework: Framework adapters for the Astro edge runtime.
• /tests: Test suites (Smoke, E2E, Worker).