# antithesishq/bombadil architecture

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

- Interactive diagram: https://gitdiagram.com/antithesishq/bombadil
- Repository: https://github.com/antithesishq/bombadil

## Overview

Bombadil is a property-based testing system for web and terminal UIs. Its core workflow is to load a user specification, explore generated actions against a UI, evaluate correctness properties, and produce traces for review; failing traces can also be shrunk. The README documents browser and terminal testing and Antithesis execution. The graph preserves those product areas, but many cross-crate calls are not shown in the sampled source, so unverified connections are dashed rather than asserted.

Main entry points: [`lib/bombadil/src/runner.rs`](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/runner.rs) (Exploration runner), [`lib/bombadil-browser/src/browser.rs`](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser.rs) (Browser control), [`lib/bombadil/src/specification/verifier.rs`](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/specification/verifier.rs) (Property verification), [`lib/bombadil-cli/src/main.rs`](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-cli/src/main.rs) (Command-line interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_spec["Specifications and properties"]
  node_specification["Specification loading<br/>[mod.rs]"]
  node_verification["Property verification<br/>[verifier.rs]"]
  node_ltl["Temporal property evaluation<br/>[eval.rs]"]
end

subgraph group_runtime["Exploration runtime"]
  node_cli["Command-line interface<br/>[main.rs]"]
  node_runner["Exploration runner<br/>[runner.rs]"]
  node_model["Action generation<br/>[model.rs]"]
  node_shrink["Trace shrinking<br/>[mod.rs]"]
end

subgraph group_adapters["UI adapters"]
  node_browser["Browser control<br/>[browser.rs]"]
  node_browser_actions["Browser actions<br/>[actions.rs]"]
  node_browser_state["Browser state<br/>[state.rs]"]
  node_browser_cookies["Cookie handling<br/>[cookie.rs]"]
  node_js_instrumentation["JavaScript instrumentation<br/>[js.rs]"]
  node_source_ids["Instrumentation IDs<br/>[source_id.rs]"]
  node_terminal["Terminal driver<br/>[driver.rs]"]
  node_terminal_pty["PTY session<br/>[pty.rs]"]
  node_terminal_extract["Terminal extraction<br/>[extractors.rs]"]
  node_cdp["Chrome DevTools transport<br/>[conn.rs]"]
end

subgraph group_results["Traces and review"]
  node_trace_writer["Trace writing<br/>[writer.rs]"]
  node_trace_reader["Trace reading<br/>[reader.rs]"]
  node_trace_record["Trace records<br/>[record.rs]"]
  node_trace_envelope["Trace envelope<br/>[envelope.rs]"]
  node_inspect["Trace inspection UI<br/>[lib.rs]"]
  node_inspect_timeline["Trace timeline<br/>[timeline.rs]"]
  node_inspect_actions["Inspector actions<br/>[actions.rs]"]
  node_inspect_container["Timeline sizing<br/>[container_size.rs]"]
  node_inspect_scroll["Timeline scrolling<br/>[list_autoscroll.rs]"]
end

subgraph group_integrations["Execution integrations"]
  node_antithesis["Antithesis execution<br/>[lib.rs]"]
end

node_developer(("Developer"))
node_trace_api["Trace API"]

node_developer -.->|"starts runs"| node_cli
node_cli -.->|"loads spec"| node_specification
node_specification -.->|"provides properties"| node_verification
node_verification -.->|"evaluates formulas"| node_ltl
node_runner -.->|"requests actions"| node_model
node_runner -.->|"checks properties"| node_verification
node_runner -.->|"drives browser"| node_browser
node_runner -.->|"drives terminal"| node_terminal
node_browser -->|"dispatches actions"| node_browser_actions
node_browser -->|"captures state"| node_browser_state
node_browser -->|"configures cookies"| node_browser_cookies
node_browser_state -->|"uses instrumentation"| node_js_instrumentation
node_js_instrumentation -->|"uses source IDs"| node_source_ids
node_browser -.->|"sends commands"| node_cdp
node_terminal -->|"uses PTY"| node_terminal_pty
node_terminal -->|"extracts state"| node_terminal_extract
node_runner -.->|"records run"| node_trace_writer
node_shrink -.->|"tests candidates"| node_verification
node_trace_writer -->|"writes records"| node_trace_record
node_trace_writer -->|"writes envelope"| node_trace_envelope
node_trace_api -->|"serves trace"| node_inspect
node_inspect -->|"renders timeline"| node_inspect_timeline
node_inspect -->|"renders actions"| node_inspect_actions
node_inspect_actions -->|"uses sizing"| node_inspect_container
node_inspect_actions -->|"uses scrolling"| node_inspect_scroll
node_trace_reader -.->|"reads records"| node_trace_record
node_cli -.->|"runs under"| node_antithesis

click node_cli "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-cli/src/main.rs"
click node_specification "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/specification/bundler/mod.rs"
click node_verification "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/specification/verifier.rs"
click node_ltl "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-ltl/src/eval.rs"
click node_runner "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/runner.rs"
click node_model "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/model.rs"
click node_shrink "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/shrink/mod.rs"
click node_browser "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser.rs"
click node_browser_actions "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser/actions.rs"
click node_browser_state "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser/state.rs"
click node_browser_cookies "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/cookie.rs"
click node_js_instrumentation "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/instrumentation/js.rs"
click node_source_ids "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/instrumentation/source_id.rs"
click node_terminal "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/driver.rs"
click node_terminal_pty "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/pty.rs"
click node_terminal_extract "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/extractors.rs"
click node_trace_writer "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/writer.rs"
click node_trace_reader "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/reader.rs"
click node_trace_record "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/record.rs"
click node_trace_envelope "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/envelope.rs"
click node_inspect "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/lib.rs"
click node_inspect_timeline "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/timeline.rs"
click node_inspect_actions "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/actions.rs"
click node_inspect_container "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/container_size.rs"
click node_inspect_scroll "https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/list_autoscroll.rs"
click node_antithesis "https://github.com/antithesishq/bombadil/blob/main/lib/antithesis-fuzzer/src/lib.rs"
click node_cdp "https://github.com/antithesishq/bombadil/blob/main/lib/cdp/src/conn.rs"

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_specification,node_verification,node_ltl toneBlue
class node_cli,node_runner,node_model,node_shrink toneAmber
class node_browser,node_browser_actions,node_browser_state,node_browser_cookies,node_js_instrumentation,node_source_ids,node_terminal,node_terminal_pty,node_terminal_extract,node_cdp,node_trace_api toneMint
class node_trace_writer,node_trace_reader,node_trace_record,node_trace_envelope,node_inspect,node_inspect_timeline,node_inspect_actions,node_inspect_container,node_inspect_scroll toneRose
class node_antithesis,node_developer toneIndigo
```

## Components

### Specifications and properties

- [Specification loading](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/specification/bundler/mod.rs): `lib/bombadil/src/specification/bundler/mod.rs`
- [Property verification](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/specification/verifier.rs): `lib/bombadil/src/specification/verifier.rs`
- [Temporal property evaluation](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-ltl/src/eval.rs): `lib/bombadil-ltl/src/eval.rs`

### Exploration runtime

- [Command-line interface](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-cli/src/main.rs): `lib/bombadil-cli/src/main.rs`
- [Exploration runner](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/runner.rs): `lib/bombadil/src/runner.rs`
- [Action generation](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/model.rs): `lib/bombadil/src/model.rs`
- [Trace shrinking](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil/src/shrink/mod.rs): `lib/bombadil/src/shrink/mod.rs`

### UI adapters

- [Browser control](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser.rs): `lib/bombadil-browser/src/browser.rs`
- [Browser actions](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser/actions.rs): `lib/bombadil-browser/src/browser/actions.rs`
- [Browser state](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/browser/state.rs): `lib/bombadil-browser/src/browser/state.rs`
- [Cookie handling](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/cookie.rs): `lib/bombadil-browser/src/cookie.rs`
- [JavaScript instrumentation](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/instrumentation/js.rs): `lib/bombadil-browser/src/instrumentation/js.rs`
- [Instrumentation IDs](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-browser/src/instrumentation/source_id.rs): `lib/bombadil-browser/src/instrumentation/source_id.rs`
- [Terminal driver](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/driver.rs): `lib/bombadil-terminal/src/driver.rs`
- [PTY session](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/pty.rs): `lib/bombadil-terminal/src/pty.rs`
- [Terminal extraction](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-terminal/src/extractors.rs): `lib/bombadil-terminal/src/extractors.rs`
- [Chrome DevTools transport](https://github.com/antithesishq/bombadil/blob/main/lib/cdp/src/conn.rs): `lib/cdp/src/conn.rs`

### Traces and review

- [Trace writing](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/writer.rs): `lib/bombadil-trace/src/writer.rs`
- [Trace reading](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/reader.rs): `lib/bombadil-trace/src/reader.rs`
- [Trace records](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/record.rs): `lib/bombadil-trace/src/record.rs`
- [Trace envelope](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-trace/src/envelope.rs): `lib/bombadil-trace/src/envelope.rs`
- [Trace inspection UI](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/lib.rs): `lib/bombadil-inspect/src/lib.rs`
- [Trace timeline](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/timeline.rs): `lib/bombadil-inspect/src/timeline.rs`
- [Inspector actions](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/actions.rs): `lib/bombadil-inspect/src/actions.rs`
- [Timeline sizing](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/container_size.rs): `lib/bombadil-inspect/src/container_size.rs`
- [Timeline scrolling](https://github.com/antithesishq/bombadil/blob/main/lib/bombadil-inspect/src/list_autoscroll.rs): `lib/bombadil-inspect/src/list_autoscroll.rs`

### Execution integrations

- [Antithesis execution](https://github.com/antithesishq/bombadil/blob/main/lib/antithesis-fuzzer/src/lib.rs): `lib/antithesis-fuzzer/src/lib.rs`

### Other components

- **Developer**
- **Trace API**

## Connections

- Developer → Command-line interface: starts runs
- Command-line interface → Specification loading: loads spec
- Specification loading → Property verification: provides properties
- Property verification → Temporal property evaluation: evaluates formulas
- Exploration runner → Action generation: requests actions
- Exploration runner → Property verification: checks properties
- Exploration runner → Browser control: drives browser
- Exploration runner → Terminal driver: drives terminal
- Browser control → Browser actions: dispatches actions (evidence: `lib/bombadil-browser/src/browser.rs`)
- Browser control → Browser state: captures state (evidence: `lib/bombadil-browser/src/browser.rs`)
- Browser control → Cookie handling: configures cookies (evidence: `lib/bombadil-browser/src/browser.rs`)
- Browser state → JavaScript instrumentation: uses instrumentation (evidence: `lib/bombadil-browser/src/browser/state.rs`)
- JavaScript instrumentation → Instrumentation IDs: uses source IDs (evidence: `lib/bombadil-browser/src/instrumentation/js.rs`)
- Browser control → Chrome DevTools transport: sends commands
- Terminal driver → PTY session: uses PTY (evidence: `lib/bombadil-terminal/src/driver.rs`)
- Terminal driver → Terminal extraction: extracts state (evidence: `lib/bombadil-terminal/src/driver.rs`)
- Exploration runner → Trace writing: records run
- Trace shrinking → Property verification: tests candidates
- Trace writing → Trace records: writes records (evidence: `lib/bombadil-trace/src/writer.rs`)
- Trace writing → Trace envelope: writes envelope (evidence: `lib/bombadil-trace/src/writer.rs`)
- Trace API → Trace inspection UI: serves trace (evidence: `lib/bombadil-inspect/src/lib.rs`)
- Trace inspection UI → Trace timeline: renders timeline (evidence: `lib/bombadil-inspect/src/lib.rs`)
- Trace inspection UI → Inspector actions: renders actions (evidence: `lib/bombadil-inspect/src/lib.rs`)
- Inspector actions → Timeline sizing: uses sizing (evidence: `lib/bombadil-inspect/src/actions.rs`)
- Inspector actions → Timeline scrolling: uses scrolling (evidence: `lib/bombadil-inspect/src/actions.rs`)
- Trace reading → Trace records: reads records
- Command-line interface → Antithesis execution: runs under
