# ferrobo/reverie architecture

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

- Interactive diagram: https://gitdiagram.com/ferrobo/reverie
- Repository: https://github.com/ferrobo/reverie

## Overview

REVERIE stress-tests an already-planned wildfire-mitigation workday: preserve a fixed checkpoint, inject a controlled failure or delay, model recovery, and measure direct versus downstream priority-work loss. Its flagship experience presents sealed, reproducible audit and verification evidence; a separate bounded live workflow edits and tests a small workday. The backend audit path is supported by sampled source references; some frontend capability links are documented in the README but their wiring was not sampled.

Main entry points: [`backend/audit.py`](https://github.com/ferrobo/reverie/blob/main/backend/audit.py) (Stress audit), [`backend/traps.py`](https://github.com/ferrobo/reverie/blob/main/backend/traps.py) (Cliff analysis), [`backend/planner.py`](https://github.com/ferrobo/reverie/blob/main/backend/planner.py) (Recovery planner), [`backend/simulator.py`](https://github.com/ferrobo/reverie/blob/main/backend/simulator.py) (Checkpoint simulator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Evidence workspace"]
  node_sealed_ui["Sealed benchmark<br/>[page.tsx]"]
  node_evidence_views["Evidence views"]
  node_workspace_map["Route map<br/>[WorkspaceMap.tsx]"]
  node_artifact_validation["Artifact validation<br/>[validation.ts]"]
end

subgraph group_live["Live stress test"]
  node_live_builder["Workday editor"]
  node_guided_tour["Guided tour<br/>[GuidedTour.tsx]"]
  node_live_proxy["Live analyze route<br/>[route.ts]"]
  node_live_api["Live API<br/>[live_api.py]"]
  node_live_adapter["Live adapter<br/>[live_adapter.py]"]
  node_live_routing["Road routing<br/>[live_routing.py]"]
end

subgraph group_engine["Crash-test engine"]
  node_jobs_config["Workday model<br/>[schemas.py]"]
  node_scenario_gen["Failure scenarios<br/>[scenarios.py]"]
  node_day_simulator["Checkpoint simulator<br/>[simulator.py]"]
  node_travel_model["Travel model<br/>[travel.py]"]
  node_audit["Stress audit<br/>[audit.py]"]
end

subgraph group_proof["Proof and recovery"]
  node_planner["Recovery planner<br/>[planner.py]"]
  node_trap_analysis["Cliff analysis<br/>[traps.py]"]
  node_verification["Commitment proof<br/>[verify.py]"]
  node_repair["Repair audit<br/>[repair.py]"]
  node_recovery_routes["Recovery route artifact<br/>[recovery_routes.py]"]
end

node_coordinator(("Workday coordinator"))

node_coordinator -->|"inspect evidence"| node_sealed_ui
node_coordinator -->|"edit workday"| node_live_builder
node_sealed_ui -.->|"validates artifacts"| node_artifact_validation
node_sealed_ui -.->|"presents evidence"| node_evidence_views
node_sealed_ui -.->|"shows routes"| node_workspace_map
node_live_builder -->|"renders tour"| node_guided_tour
node_live_builder -.->|"submits analysis"| node_live_proxy
node_live_proxy -.->|"requests analysis"| node_live_api
node_live_api -->|"delegates"| node_live_adapter
node_live_api -->|"uses schemas"| node_jobs_config
node_live_api -.->|"uses routing"| node_live_routing
node_audit -->|"reads models"| node_jobs_config
node_audit -->|"generates scenarios"| node_scenario_gen
node_audit -->|"simulates checkpoints"| node_day_simulator
node_audit -->|"solves recovery"| node_planner
node_planner -->|"uses models"| node_jobs_config
node_planner -->|"uses simulation types"| node_day_simulator
node_planner -->|"uses travel data"| node_travel_model
node_day_simulator -->|"updates state"| node_jobs_config
node_day_simulator -->|"reads travel times"| node_travel_model
node_trap_analysis -->|"analyzes audit"| node_audit
node_trap_analysis -->|"uses recovery plans"| node_planner
node_trap_analysis -->|"uses crash results"| node_day_simulator
node_trap_analysis -->|"checks travel provenance"| node_travel_model
node_recovery_routes -->|"normalizes recovery state"| node_planner
node_recovery_routes -->|"uses scenarios"| node_scenario_gen
node_recovery_routes -->|"uses models"| node_jobs_config
node_recovery_routes -->|"reads crash state"| node_day_simulator
node_recovery_routes -->|"materializes route geometry"| node_travel_model
node_trap_analysis -.->|"selects proof candidates"| node_verification
node_verification -.->|"informs repair"| node_repair
node_audit -.->|"projects loss matrix"| node_trap_analysis

click node_sealed_ui "https://github.com/ferrobo/reverie/blob/main/frontend/app/page.tsx"
click node_evidence_views "https://github.com/ferrobo/reverie/tree/main/frontend/components"
click node_workspace_map "https://github.com/ferrobo/reverie/blob/main/frontend/components/WorkspaceMap.tsx"
click node_artifact_validation "https://github.com/ferrobo/reverie/blob/main/frontend/lib/validation.ts"
click node_live_builder "https://github.com/ferrobo/reverie/blob/main/frontend/app/crash-test/LiveWorkdayBuilder.tsx"
click node_guided_tour "https://github.com/ferrobo/reverie/blob/main/frontend/app/crash-test/GuidedTour.tsx"
click node_live_proxy "https://github.com/ferrobo/reverie/blob/main/frontend/app/api/live/analyze/route.ts"
click node_live_api "https://github.com/ferrobo/reverie/blob/main/backend/live_api.py"
click node_live_adapter "https://github.com/ferrobo/reverie/blob/main/backend/live_adapter.py"
click node_live_routing "https://github.com/ferrobo/reverie/blob/main/backend/live_routing.py"
click node_jobs_config "https://github.com/ferrobo/reverie/blob/main/backend/schemas.py"
click node_scenario_gen "https://github.com/ferrobo/reverie/blob/main/backend/scenarios.py"
click node_day_simulator "https://github.com/ferrobo/reverie/blob/main/backend/simulator.py"
click node_travel_model "https://github.com/ferrobo/reverie/blob/main/backend/travel.py"
click node_audit "https://github.com/ferrobo/reverie/blob/main/backend/audit.py"
click node_planner "https://github.com/ferrobo/reverie/blob/main/backend/planner.py"
click node_trap_analysis "https://github.com/ferrobo/reverie/blob/main/backend/traps.py"
click node_verification "https://github.com/ferrobo/reverie/blob/main/backend/verify.py"
click node_repair "https://github.com/ferrobo/reverie/blob/main/backend/repair.py"
click node_recovery_routes "https://github.com/ferrobo/reverie/blob/main/backend/recovery_routes.py"

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_sealed_ui,node_evidence_views,node_workspace_map,node_artifact_validation toneBlue
class node_live_builder,node_guided_tour,node_live_proxy,node_live_api,node_live_adapter,node_live_routing toneAmber
class node_jobs_config,node_scenario_gen,node_day_simulator,node_travel_model,node_audit toneMint
class node_planner,node_trap_analysis,node_verification,node_repair,node_recovery_routes toneRose
class node_coordinator toneIndigo
```

## Components

### Evidence workspace

- [Sealed benchmark](https://github.com/ferrobo/reverie/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Evidence views](https://github.com/ferrobo/reverie/tree/main/frontend/components): `frontend/components`
- [Route map](https://github.com/ferrobo/reverie/blob/main/frontend/components/WorkspaceMap.tsx): `frontend/components/WorkspaceMap.tsx`
- [Artifact validation](https://github.com/ferrobo/reverie/blob/main/frontend/lib/validation.ts): `frontend/lib/validation.ts`

### Live stress test

- [Workday editor](https://github.com/ferrobo/reverie/blob/main/frontend/app/crash-test/LiveWorkdayBuilder.tsx): `frontend/app/crash-test/LiveWorkdayBuilder.tsx`
- [Guided tour](https://github.com/ferrobo/reverie/blob/main/frontend/app/crash-test/GuidedTour.tsx): `frontend/app/crash-test/GuidedTour.tsx`
- [Live analyze route](https://github.com/ferrobo/reverie/blob/main/frontend/app/api/live/analyze/route.ts): `frontend/app/api/live/analyze/route.ts`
- [Live API](https://github.com/ferrobo/reverie/blob/main/backend/live_api.py): `backend/live_api.py`
- [Live adapter](https://github.com/ferrobo/reverie/blob/main/backend/live_adapter.py): `backend/live_adapter.py`
- [Road routing](https://github.com/ferrobo/reverie/blob/main/backend/live_routing.py): `backend/live_routing.py`

### Crash-test engine

- [Workday model](https://github.com/ferrobo/reverie/blob/main/backend/schemas.py): `backend/schemas.py`
- [Failure scenarios](https://github.com/ferrobo/reverie/blob/main/backend/scenarios.py): `backend/scenarios.py`
- [Checkpoint simulator](https://github.com/ferrobo/reverie/blob/main/backend/simulator.py): `backend/simulator.py`
- [Travel model](https://github.com/ferrobo/reverie/blob/main/backend/travel.py): `backend/travel.py`
- [Stress audit](https://github.com/ferrobo/reverie/blob/main/backend/audit.py): `backend/audit.py`

### Proof and recovery

- [Recovery planner](https://github.com/ferrobo/reverie/blob/main/backend/planner.py): `backend/planner.py`
- [Cliff analysis](https://github.com/ferrobo/reverie/blob/main/backend/traps.py): `backend/traps.py`
- [Commitment proof](https://github.com/ferrobo/reverie/blob/main/backend/verify.py): `backend/verify.py`
- [Repair audit](https://github.com/ferrobo/reverie/blob/main/backend/repair.py): `backend/repair.py`
- [Recovery route artifact](https://github.com/ferrobo/reverie/blob/main/backend/recovery_routes.py): `backend/recovery_routes.py`

### Other components

- **Workday coordinator**

## Connections

- Workday coordinator → Sealed benchmark: inspect evidence
- Workday coordinator → Workday editor: edit workday
- Sealed benchmark → Artifact validation: validates artifacts
- Sealed benchmark → Evidence views: presents evidence
- Sealed benchmark → Route map: shows routes
- Workday editor → Guided tour: renders tour (evidence: `frontend/app/crash-test/LiveWorkdayBuilder.tsx`)
- Workday editor → Live analyze route: submits analysis
- Live analyze route → Live API: requests analysis
- Live API → Live adapter: delegates (evidence: `backend/live_api.py`)
- Live API → Workday model: uses schemas (evidence: `backend/live_api.py`)
- Live API → Road routing: uses routing
- Stress audit → Workday model: reads models (evidence: `backend/audit.py`)
- Stress audit → Failure scenarios: generates scenarios (evidence: `backend/audit.py`)
- Stress audit → Checkpoint simulator: simulates checkpoints (evidence: `backend/audit.py`)
- Stress audit → Recovery planner: solves recovery (evidence: `backend/audit.py`)
- Recovery planner → Workday model: uses models (evidence: `backend/planner.py`)
- Recovery planner → Checkpoint simulator: uses simulation types (evidence: `backend/planner.py`)
- Recovery planner → Travel model: uses travel data (evidence: `backend/planner.py`)
- Checkpoint simulator → Workday model: updates state (evidence: `backend/simulator.py`)
- Checkpoint simulator → Travel model: reads travel times (evidence: `backend/simulator.py`)
- Cliff analysis → Stress audit: analyzes audit (evidence: `backend/traps.py`)
- Cliff analysis → Recovery planner: uses recovery plans (evidence: `backend/traps.py`)
- Cliff analysis → Checkpoint simulator: uses crash results (evidence: `backend/traps.py`)
- Cliff analysis → Travel model: checks travel provenance (evidence: `backend/traps.py`)
- Recovery route artifact → Recovery planner: normalizes recovery state (evidence: `backend/recovery_routes.py`)
- Recovery route artifact → Failure scenarios: uses scenarios (evidence: `backend/recovery_routes.py`)
- Recovery route artifact → Workday model: uses models (evidence: `backend/recovery_routes.py`)
- Recovery route artifact → Checkpoint simulator: reads crash state (evidence: `backend/recovery_routes.py`)
- Recovery route artifact → Travel model: materializes route geometry (evidence: `backend/recovery_routes.py`)
- Cliff analysis → Commitment proof: selects proof candidates
- Commitment proof → Repair audit: informs repair
- Stress audit → Cliff analysis: projects loss matrix (evidence: `backend/traps.py`)
