Architecture
A run has four stages: cast, run, review and board. Each stage reads and writes plain files, so you can replace any stage or run it by hand. Anything that touches a cloud, a model or a target platform sits behind an adapter. Data residency is a per-market setting that every adapter must satisfy.
Stages
- Cast
personas/*/profile.md, prompt, scenarios - Target adapterPreview URL, test user, fixtures
- LLM provider adapterChosen per market
- RunReal browser over WebDriver BiDi. Steps, screenshots, console, network
- Run recordJSON and PNG
- Deterministic checksaxe, CSP, status codes, allowed hosts
- ReviewerClaim by claim, code references, 3 votes
- Record batchCorroborations, candidates
- Person checks high-severity candidates
- Results boardStatic HTML and JSON
Amber marks the stages where a model acts. Blue marks adapters. Green marks what people read.
Adapters
| Adapter | Responsibility | First implementations |
|---|---|---|
| Target | Resolve a preview for a change (PR number, branch or URL); create a test user with a named role; seed fixtures; say which hosts a run may touch | Plain URL; then Vercel, Netlify, Cloudflare Pages, GitHub Deployments |
| LLM provider | Play the persona; review claims. Separate models for the two jobs | Vertex AI (Gemini), Azure AI Foundry, Anthropic, OpenAI-compatible local |
| Runner host | Where the browser runs | Laptop; GitHub Actions; Kubernetes job (Helm); Cloud Run jobs; Azure Container Apps jobs |
| Results store | Where run records and the board live | Local directory; object storage (GCS, Azure Blob, S3); the board is always static files on top |
| Secrets | Test-user credentials and provider keys | OS keychain; CI secrets; Secret Manager; Key Vault |
An adapter declares the regions it can run in. A market profile (for example uk) lists the regions
that satisfy it (europe-west2, uksouth, ukwest). A run refuses to start if any adapter in the chain
cannot satisfy the market.
The evidence rule
A finding is a claim plus evidence. The reviewer rejects a claim unless a step in the run record supports it. That support is a screenshot, a console or network line, or a code reference. Each finding carries one of four tags:
| Tag | Meaning |
|---|---|
| measured | Seen in a run |
| code | Read in the source |
| sourced | Stated in an issue or document |
| inferred | Our reasoning, labelled as such |
High-severity findings wait for a person to confirm them.
Browsers
Chrome and Firefox are driven through WebDriver BiDi, so the same session code drives both. Mobile is a viewport and user-agent profile per persona. Real devices will come through an adapter for a hosted browser grid.
Deployment
deploy/composeruns everything on one machine with one command.deploy/helm/dummyrunis a Helm chart with jobs for the runner and the reviewer and a board publisher. It has a values file per cloud (values-gcp.yamlandvalues-azure.yaml).- Every release runs the demo cast against the demo app on both clouds and compares the two boards.