# hamc/blastproof architecture

> Architecture diagram of the GitHub repository hamc/blastproof, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamc/blastproof
- Repository: https://github.com/hamc/blastproof

## Overview

blastproof is a local/CI AI-assisted end-to-end testing agent: users configure a project, describe tests in YAML, and run them against a real browser. The run path checks prerequisites, optionally narrows tests to those affected by a diff, establishes authentication, executes browser actions judged by a model, then scores and reports the gate result. Separate capabilities scaffold setup and draft uncovered-route tests. The map follows README statements and SOURCE INDEX references; several unsampled subsystems are represented by their exact directories, so their internal wiring is not inferred.

Main entry points: [`src/commands/run.ts`](https://github.com/hamc/blastproof/blob/main/src/commands/run.ts) (Run command), [`src/commands/plan.ts`](https://github.com/hamc/blastproof/blob/main/src/commands/plan.ts) (Plan command), [`src/runner/executor.ts`](https://github.com/hamc/blastproof/blob/main/src/runner/executor.ts) (Test executor), [`src/llm/brain.ts`](https://github.com/hamc/blastproof/blob/main/src/llm/brain.ts) (Agent and judge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Project setup"]
  node_init["Project init<br/>[init.ts]"]
  node_config["Configuration<br/>[config.ts]"]
end

subgraph group_selection["Test selection"]
  node_testfiles["YAML test files<br/>[testfile.ts]"]
  node_run["Run command<br/>[run.ts]"]
  node_diff["Diff analysis<br/>[diff.ts]"]
  node_impact["Impact mapping<br/>[impact.ts]"]
end

subgraph group_execution["Browser execution"]
  node_preflight["Preflight checks<br/>[preflight.ts]"]
  node_auth["Session authentication<br/>[auth.ts]"]
  node_executor["Test executor<br/>[executor.ts]"]
  node_browser_actions["Browser actions<br/>[actions.ts]"]
  node_snapshots["Accessibility snapshots<br/>[snapshot.ts]"]
  node_env["Secrets and env<br/>[env.ts]"]
  node_budget["Run budget<br/>[budget.ts]"]
end

subgraph group_intelligence["AI and planning"]
  node_brain["Agent and judge<br/>[brain.ts]"]
  node_prompts["Model prompts<br/>[prompts.ts]"]
  node_schemas["Action schemas<br/>[schemas.ts]"]
  node_provider["Model provider<br/>[provider.ts]"]
  node_planner["Test planner<br/>[planner.ts]"]
  node_plan_command["Plan command<br/>[plan.ts]"]
end

subgraph group_results["Results and reports"]
  node_score["Run scoring<br/>[score.ts]"]
  node_reports["HTML and JUnit<br/>[html.ts]"]
  node_warnings["Run warnings<br/>[warnings.ts]"]
end

node_developer(("Developer / CI"))
node_cli["CLI<br/>[cli.ts]"]

node_developer -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_run
node_cli -->|"dispatches"| node_plan_command
node_init -->|"scaffolds"| node_config
node_developer -->|"writes"| node_testfiles
node_run -->|"loads"| node_config
node_run -->|"discovers and parses"| node_testfiles
node_run -->|"checks changes"| node_diff
node_run -->|"selects affected tests"| node_impact
node_run -->|"checks prerequisites"| node_preflight
node_run -->|"prepares session"| node_auth
node_run -->|"executes tests"| node_executor
node_executor -->|"performs actions"| node_browser_actions
node_executor -->|"reads snapshots"| node_snapshots
node_executor -->|"resolves and masks"| node_env
node_executor -->|"requests judgments"| node_brain
node_brain -->|"builds prompts"| node_prompts
node_brain -->|"validates output"| node_schemas
node_brain -->|"bounds calls"| node_budget
node_preflight -->|"checks model"| node_provider
node_brain -.->|"uses model"| node_provider
node_run -->|"scores results"| node_score
node_run -->|"writes reports"| node_reports
node_run -->|"collects warnings"| node_warnings
node_plan_command -->|"loads"| node_config
node_plan_command -->|"drafts tests"| node_planner
node_plan_command -->|"finds uncovered routes"| node_impact
node_plan_command -->|"checks prerequisites"| node_preflight
node_plan_command -->|"reads test coverage"| node_testfiles
node_plan_command -->|"reports score"| node_score

click node_cli "https://github.com/hamc/blastproof/blob/main/src/cli.ts"
click node_init "https://github.com/hamc/blastproof/blob/main/src/commands/init.ts"
click node_config "https://github.com/hamc/blastproof/blob/main/src/config.ts"
click node_testfiles "https://github.com/hamc/blastproof/blob/main/src/runner/testfile.ts"
click node_run "https://github.com/hamc/blastproof/blob/main/src/commands/run.ts"
click node_diff "https://github.com/hamc/blastproof/blob/main/src/diff.ts"
click node_impact "https://github.com/hamc/blastproof/blob/main/src/impact.ts"
click node_preflight "https://github.com/hamc/blastproof/blob/main/src/preflight.ts"
click node_auth "https://github.com/hamc/blastproof/blob/main/src/auth.ts"
click node_executor "https://github.com/hamc/blastproof/blob/main/src/runner/executor.ts"
click node_browser_actions "https://github.com/hamc/blastproof/blob/main/src/runner/actions.ts"
click node_snapshots "https://github.com/hamc/blastproof/blob/main/src/runner/snapshot.ts"
click node_env "https://github.com/hamc/blastproof/blob/main/src/runner/env.ts"
click node_budget "https://github.com/hamc/blastproof/blob/main/src/runner/budget.ts"
click node_brain "https://github.com/hamc/blastproof/blob/main/src/llm/brain.ts"
click node_prompts "https://github.com/hamc/blastproof/blob/main/src/llm/prompts.ts"
click node_schemas "https://github.com/hamc/blastproof/blob/main/src/llm/schemas.ts"
click node_provider "https://github.com/hamc/blastproof/blob/main/src/llm/provider.ts"
click node_planner "https://github.com/hamc/blastproof/blob/main/src/planner.ts"
click node_plan_command "https://github.com/hamc/blastproof/blob/main/src/commands/plan.ts"
click node_score "https://github.com/hamc/blastproof/blob/main/src/report/score.ts"
click node_reports "https://github.com/hamc/blastproof/blob/main/src/report/html.ts"
click node_warnings "https://github.com/hamc/blastproof/blob/main/src/report/warnings.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_init,node_config toneBlue
class node_testfiles,node_run,node_diff,node_impact toneAmber
class node_preflight,node_auth,node_executor,node_browser_actions,node_snapshots,node_env,node_budget toneMint
class node_brain,node_prompts,node_schemas,node_provider,node_planner,node_plan_command toneRose
class node_score,node_reports,node_warnings,node_developer toneIndigo
class node_cli toneTeal
```

## Components

### Project setup

- [Project init](https://github.com/hamc/blastproof/blob/main/src/commands/init.ts): `src/commands/init.ts`
- [Configuration](https://github.com/hamc/blastproof/blob/main/src/config.ts): `src/config.ts`

### Test selection

- [YAML test files](https://github.com/hamc/blastproof/blob/main/src/runner/testfile.ts): `src/runner/testfile.ts`
- [Run command](https://github.com/hamc/blastproof/blob/main/src/commands/run.ts): `src/commands/run.ts`
- [Diff analysis](https://github.com/hamc/blastproof/blob/main/src/diff.ts): `src/diff.ts`
- [Impact mapping](https://github.com/hamc/blastproof/blob/main/src/impact.ts): `src/impact.ts`

### Browser execution

- [Preflight checks](https://github.com/hamc/blastproof/blob/main/src/preflight.ts): `src/preflight.ts`
- [Session authentication](https://github.com/hamc/blastproof/blob/main/src/auth.ts): `src/auth.ts`
- [Test executor](https://github.com/hamc/blastproof/blob/main/src/runner/executor.ts): `src/runner/executor.ts`
- [Browser actions](https://github.com/hamc/blastproof/blob/main/src/runner/actions.ts): `src/runner/actions.ts`
- [Accessibility snapshots](https://github.com/hamc/blastproof/blob/main/src/runner/snapshot.ts): `src/runner/snapshot.ts`
- [Secrets and env](https://github.com/hamc/blastproof/blob/main/src/runner/env.ts): `src/runner/env.ts`
- [Run budget](https://github.com/hamc/blastproof/blob/main/src/runner/budget.ts): `src/runner/budget.ts`

### AI and planning

- [Agent and judge](https://github.com/hamc/blastproof/blob/main/src/llm/brain.ts): `src/llm/brain.ts`
- [Model prompts](https://github.com/hamc/blastproof/blob/main/src/llm/prompts.ts): `src/llm/prompts.ts`
- [Action schemas](https://github.com/hamc/blastproof/blob/main/src/llm/schemas.ts): `src/llm/schemas.ts`
- [Model provider](https://github.com/hamc/blastproof/blob/main/src/llm/provider.ts): `src/llm/provider.ts`
- [Test planner](https://github.com/hamc/blastproof/blob/main/src/planner.ts): `src/planner.ts`
- [Plan command](https://github.com/hamc/blastproof/blob/main/src/commands/plan.ts): `src/commands/plan.ts`

### Results and reports

- [Run scoring](https://github.com/hamc/blastproof/blob/main/src/report/score.ts): `src/report/score.ts`
- [HTML and JUnit](https://github.com/hamc/blastproof/blob/main/src/report/html.ts): `src/report/html.ts`
- [Run warnings](https://github.com/hamc/blastproof/blob/main/src/report/warnings.ts): `src/report/warnings.ts`

### Other components

- **Developer / CI**
- [CLI](https://github.com/hamc/blastproof/blob/main/src/cli.ts): `src/cli.ts`

## Connections

- Developer / CI → CLI: invokes
- CLI → Project init: dispatches (evidence: `src/cli.ts`)
- CLI → Run command: dispatches (evidence: `src/cli.ts`)
- CLI → Plan command: dispatches (evidence: `src/cli.ts`)
- Project init → Configuration: scaffolds (evidence: `src/commands/init.ts`)
- Developer / CI → YAML test files: writes
- Run command → Configuration: loads (evidence: `src/commands/run.ts`)
- Run command → YAML test files: discovers and parses (evidence: `src/commands/run.ts`)
- Run command → Diff analysis: checks changes (evidence: `src/commands/run.ts`)
- Run command → Impact mapping: selects affected tests (evidence: `src/commands/run.ts`)
- Run command → Preflight checks: checks prerequisites (evidence: `src/commands/run.ts`)
- Run command → Session authentication: prepares session (evidence: `src/commands/run.ts`)
- Run command → Test executor: executes tests (evidence: `src/commands/run.ts`)
- Test executor → Browser actions: performs actions (evidence: `src/runner/executor.ts`)
- Test executor → Accessibility snapshots: reads snapshots (evidence: `src/runner/executor.ts`)
- Test executor → Secrets and env: resolves and masks (evidence: `src/commands/run.ts`)
- Test executor → Agent and judge: requests judgments (evidence: `src/runner/executor.ts`)
- Agent and judge → Model prompts: builds prompts (evidence: `src/llm/brain.ts`)
- Agent and judge → Action schemas: validates output (evidence: `src/llm/brain.ts`)
- Agent and judge → Run budget: bounds calls (evidence: `src/llm/brain.ts`)
- Preflight checks → Model provider: checks model (evidence: `src/preflight.ts`)
- Agent and judge → Model provider: uses model
- Run command → Run scoring: scores results (evidence: `src/commands/run.ts`)
- Run command → HTML and JUnit: writes reports (evidence: `src/commands/run.ts`)
- Run command → Run warnings: collects warnings (evidence: `src/commands/run.ts`)
- Plan command → Configuration: loads (evidence: `src/commands/plan.ts`)
- Plan command → Test planner: drafts tests (evidence: `src/commands/plan.ts`)
- Plan command → Impact mapping: finds uncovered routes (evidence: `src/commands/plan.ts`)
- Plan command → Preflight checks: checks prerequisites (evidence: `src/commands/plan.ts`)
- Plan command → YAML test files: reads test coverage (evidence: `src/commands/plan.ts`)
- Plan command → Run scoring: reports score (evidence: `src/commands/plan.ts`)
