Architecture

How to read the diagrams

Start on the left and follow the arrows. The person never runs the examples in the hosted UI; pages are built from the corpus. Ask AI talks to the FAQ matcher, not a live model. Hosting details stay on the physical diagram so the logical one does not name GitHub Pages.

• Logical: what each layer may do. Presentation never invents scenario facts.
• Physical: one GitHub Pages site plus Actions for test, capture, and deploy. CI is not on the request path.

Logical

What the production app does. No hosts or vendors here — only responsibilities. There is no user store: a page is HTML plus files baked in at build time.

%%{init: {"flowchart": {"htmlLabels": true, "padding": 20, "wrappingWidth": 260, "nodeSpacing": 48, "rankSpacing": 56}}}%%
flowchart LR
  person["Person"]

  subgraph pages["Pages"]
    home["Home"]
    scenarios["Scenarios"]
    ask["Ask AI"]
    vision["Vision"]
    arch["Architecture"]
  end

  subgraph site["Site"]
    astro["Astro"]
    faq["FAQ"]
  end

  subgraph corpus["Corpus"]
    json["scenario.json"]
    examples["examples"]
    results["Results"]
  end

  person --> home --> astro
  person --> scenarios --> astro
  person --> ask --> astro --> faq
  person --> vision --> astro
  person --> arch --> astro
  astro --> json
  astro --> examples
  astro --> results

• Pages: Home, scenario list and detail, Ask AI, Quality, Vision, Architecture, Run locally, release notes
• Site: Build HTML from the corpus; match Ask questions to the FAQ
• Corpus: Scenario metadata, example source, and CI-cached result logs

Physical

How that system is hosted in production. Compute is build-scoped. There is no application database.

%%{init: {"flowchart": {"htmlLabels": true, "padding": 20, "wrappingWidth": 280, "nodeSpacing": 56, "rankSpacing": 72}}}%%
flowchart LR
  browser["Browser"]

  subgraph pageshost["GitHub Pages"]
    html["Static HTML"]
    files["Static files"]
  end

  cdns["Public CDNs"]
  github["GitHub main"]
  actions["GitHub Actions"]

  browser -->|HTML| html
  browser -->|"CSS · images · results"| files
  browser -->|"Fonts · Mermaid"| cdns
  github --> actions
  actions -->|deploy| pageshost

• HTML: Astro static files in `apps/web/dist` on GitHub Pages
• Static files: CSS, images, logo, and cached `public/results/` JSON from the same Pages artifact
• Public CDNs: Google Fonts on every page; Mermaid only on Architecture
• Corpus: Read at build time from `examples/`, `docs/plan/`, and `apps/web/src/lib/ask.ts`
• Identity / data store: None
• CI / release: GitHub Actions on `main`; Pages deploys only after `test-and-build`

What this omits on purpose

There is no user store, no session, and no live test-runner service. Examples run in CI and on a local clone. Product intent — who this is for, and what it must not claim — lives on the Vision page, not here.