# zeta92/atrezzo architecture

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

- Interactive diagram: https://gitdiagram.com/zeta92/atrezzo
- Repository: https://github.com/zeta92/atrezzo

## Overview

atrezzo turns a declared scenario into deterministic application state, serves contract-based API projections, and checks whether a flow renders the expected screen. Its CLI also supports importing API specs, harvesting observed app behavior, runtime generation, and diagnosing unresolved route gaps. The graph follows documented workflow and sampled dependency references; unsampled subsystems are represented only where the README or source index supports them.

Main entry points: [`scripts/cli.mjs`](https://github.com/zeta92/atrezzo/blob/main/scripts/cli.mjs) (CLI), [`scripts/lib/serve.mjs`](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/serve.mjs) (Mock server), [`scripts/lib/scenario.mjs`](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/scenario.mjs) (Scenario model), [`scripts/lib/world.mjs`](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/world.mjs) (Seeded world)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Scenario authoring"]
  node_scenario["Scenario model<br/>[scenario.mjs]"]
  node_yaml["YAML parser<br/>[yaml.mjs]"]
  node_openapi["OpenAPI import<br/>[openapi.mjs]"]
  node_harvest["App harvest<br/>[harvest.mjs]"]
  node_project["Project config<br/>[project.mjs]"]
end

subgraph group_state["State and projection"]
  node_world["Seeded world<br/>[world.mjs]"]
  node_prng["Seeded random<br/>[prng.mjs]"]
  node_contract["Projection engine<br/>[contract.mjs]"]
end

subgraph group_runtime["Mock runtimes"]
  node_codegen["Runtime codegen<br/>[codegen.mjs]"]
  node_runtime_registry["Runtime registry<br/>[index.mjs]"]
  node_runtime_adapters["Runtime adapters"]
  node_server["Mock server<br/>[serve.mjs]"]
  node_passthrough["Passthrough fixtures<br/>[passthrough.mjs]"]
end

subgraph group_feedback["Screen verification"]
  node_flow["Verification flow<br/>[flows.mjs]"]
  node_verify["Screen verifier<br/>[verify.mjs]"]
end

subgraph group_operations["Project operations"]
  node_misses[("Route gaps<br/>[misses.mjs]")]
  node_doctor["Project doctor<br/>[doctor.mjs]"]
  node_record["Request recording<br/>[record.mjs]"]
end

node_developer(("Developer"))
node_cli["CLI<br/>[cli.mjs]"]
node_browser(("Application screen"))

node_developer -->|"runs commands"| node_cli
node_cli -->|"loads scenarios"| node_scenario
node_cli -->|"generates state"| node_world
node_cli -->|"starts mock"| node_server
node_cli -->|"runs checks"| node_verify
node_cli -->|"imports specs"| node_openapi
node_cli -->|"harvests app"| node_harvest
node_cli -->|"selects runtimes"| node_runtime_registry
node_cli -->|"reads config"| node_project
node_cli -->|"checks project"| node_doctor
node_cli -->|"lists gaps"| node_misses
node_cli -->|"records traffic"| node_record
node_scenario -->|"parses input"| node_yaml
node_scenario -->|"uses templates"| node_world
node_scenario -->|"resolves fixtures"| node_passthrough
node_world -->|"seeds generation"| node_prng
node_harvest -->|"normalizes scenario"| node_scenario
node_harvest -->|"generates sample state"| node_world
node_server -->|"loads scenario"| node_scenario
node_server -->|"builds dataset"| node_world
node_server -->|"handles requests"| node_contract
node_server -->|"records gaps"| node_misses
node_runtime_registry -->|"dispatches adapters"| node_runtime_adapters
node_runtime_adapters -->|"generates handlers"| node_codegen
node_verify -->|"resets expected state"| node_world
node_verify -->|"checks rendered DOM"| node_browser
node_browser -->|"requests mock API"| node_server
node_verify -->|"resets mock"| node_server
node_doctor -->|"checks scenario"| node_scenario
node_doctor -->|"checks generated state"| node_world

click node_cli "https://github.com/zeta92/atrezzo/blob/main/scripts/cli.mjs"
click node_scenario "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/scenario.mjs"
click node_yaml "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/yaml.mjs"
click node_openapi "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/openapi.mjs"
click node_harvest "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/harvest.mjs"
click node_project "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/project.mjs"
click node_world "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/world.mjs"
click node_prng "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/prng.mjs"
click node_contract "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/contract.mjs"
click node_codegen "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/codegen.mjs"
click node_runtime_registry "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/runtimes/index.mjs"
click node_runtime_adapters "https://github.com/zeta92/atrezzo/tree/main/scripts/lib/runtimes"
click node_server "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/serve.mjs"
click node_misses "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/misses.mjs"
click node_passthrough "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/passthrough.mjs"
click node_flow "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/flows.mjs"
click node_verify "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/verify.mjs"
click node_doctor "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/doctor.mjs"
click node_record "https://github.com/zeta92/atrezzo/blob/main/scripts/lib/record.mjs"

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_scenario,node_yaml,node_openapi,node_harvest,node_project,node_browser toneBlue
class node_world,node_prng,node_contract toneAmber
class node_codegen,node_runtime_registry,node_runtime_adapters,node_server,node_passthrough toneMint
class node_flow,node_verify toneRose
class node_misses,node_doctor,node_record,node_developer toneIndigo
class node_cli toneTeal
```

## Components

### Scenario authoring

- [Scenario model](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/scenario.mjs): `scripts/lib/scenario.mjs`
- [YAML parser](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/yaml.mjs): `scripts/lib/yaml.mjs`
- [OpenAPI import](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/openapi.mjs): `scripts/lib/openapi.mjs`
- [App harvest](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/harvest.mjs): `scripts/lib/harvest.mjs`
- [Project config](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/project.mjs): `scripts/lib/project.mjs`

### State and projection

- [Seeded world](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/world.mjs): `scripts/lib/world.mjs`
- [Seeded random](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/prng.mjs): `scripts/lib/prng.mjs`
- [Projection engine](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/contract.mjs): `scripts/lib/contract.mjs`

### Mock runtimes

- [Runtime codegen](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/codegen.mjs): `scripts/lib/codegen.mjs`
- [Runtime registry](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/runtimes/index.mjs): `scripts/lib/runtimes/index.mjs`
- [Runtime adapters](https://github.com/zeta92/atrezzo/tree/main/scripts/lib/runtimes): `scripts/lib/runtimes`
- [Mock server](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/serve.mjs): `scripts/lib/serve.mjs`
- [Passthrough fixtures](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/passthrough.mjs): `scripts/lib/passthrough.mjs`

### Screen verification

- [Verification flow](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/flows.mjs): `scripts/lib/flows.mjs`
- [Screen verifier](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/verify.mjs): `scripts/lib/verify.mjs`

### Project operations

- [Route gaps](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/misses.mjs): `scripts/lib/misses.mjs`
- [Project doctor](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/doctor.mjs): `scripts/lib/doctor.mjs`
- [Request recording](https://github.com/zeta92/atrezzo/blob/main/scripts/lib/record.mjs): `scripts/lib/record.mjs`

### Other components

- **Developer**
- [CLI](https://github.com/zeta92/atrezzo/blob/main/scripts/cli.mjs): `scripts/cli.mjs`
- **Application screen**

## Connections

- Developer → CLI: runs commands (evidence: `README.md`)
- CLI → Scenario model: loads scenarios (evidence: `scripts/cli.mjs`)
- CLI → Seeded world: generates state (evidence: `scripts/cli.mjs`)
- CLI → Mock server: starts mock (evidence: `scripts/cli.mjs`)
- CLI → Screen verifier: runs checks (evidence: `scripts/cli.mjs`)
- CLI → OpenAPI import: imports specs (evidence: `scripts/cli.mjs`)
- CLI → App harvest: harvests app (evidence: `scripts/cli.mjs`)
- CLI → Runtime registry: selects runtimes (evidence: `scripts/cli.mjs`)
- CLI → Project config: reads config (evidence: `scripts/cli.mjs`)
- CLI → Project doctor: checks project (evidence: `scripts/cli.mjs`)
- CLI → Route gaps: lists gaps (evidence: `scripts/cli.mjs`)
- CLI → Request recording: records traffic (evidence: `scripts/cli.mjs`)
- Scenario model → YAML parser: parses input (evidence: `scripts/lib/scenario.mjs`)
- Scenario model → Seeded world: uses templates (evidence: `scripts/lib/scenario.mjs`)
- Scenario model → Passthrough fixtures: resolves fixtures (evidence: `scripts/lib/scenario.mjs`)
- Seeded world → Seeded random: seeds generation (evidence: `scripts/lib/world.mjs`)
- App harvest → Scenario model: normalizes scenario (evidence: `scripts/lib/harvest.mjs`)
- App harvest → Seeded world: generates sample state (evidence: `scripts/lib/harvest.mjs`)
- Mock server → Scenario model: loads scenario (evidence: `scripts/lib/serve.mjs`)
- Mock server → Seeded world: builds dataset (evidence: `scripts/lib/serve.mjs`)
- Mock server → Projection engine: handles requests (evidence: `scripts/lib/serve.mjs`)
- Mock server → Route gaps: records gaps (evidence: `scripts/lib/serve.mjs`)
- Runtime registry → Runtime adapters: dispatches adapters (evidence: `scripts/lib/runtimes/index.mjs`)
- Runtime adapters → Runtime codegen: generates handlers (evidence: `scripts/lib/runtimes/msw.mjs`)
- Screen verifier → Seeded world: resets expected state (evidence: `scripts/lib/verify.mjs`)
- Screen verifier → Application screen: checks rendered DOM (evidence: `README.md`)
- Application screen → Mock server: requests mock API (evidence: `README.md`)
- Screen verifier → Mock server: resets mock (evidence: `scripts/lib/verify.mjs`)
- Project doctor → Scenario model: checks scenario (evidence: `scripts/lib/doctor.mjs`)
- Project doctor → Seeded world: checks generated state (evidence: `scripts/lib/doctor.mjs`)
