# candavere/lattice architecture

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

- Interactive diagram: https://gitdiagram.com/candavere/lattice
- Repository: https://github.com/candavere/lattice

## Overview

Lattice is a deterministic, partially observable multi-agent research environment; its agents are evaluation subjects, not the product. The main workflow is to run a seeded simulation, record its steps, then verify, render, analyze, or replay that recording. Separate evaluation and benchmarking workflows produce evaluation and throughput artifacts; evaluation can seat an external process through the wire protocol. The README documents these command paths and major capabilities. Sampled source confirms simulation, policy, replay, protocol, and rendering behavior; links for unsampled subsystems rely on the README, so uncertain internal call wiring is omitted.

Main entry points: [`Cli/CliApp.cs`](https://github.com/candavere/lattice/blob/main/Cli/CliApp.cs) (Command App), [`Agents/ScenarioRunner.cs`](https://github.com/candavere/lattice/blob/main/Agents/ScenarioRunner.cs) (Scenario Runner), [`Agents/PairedEvaluation.cs`](https://github.com/candavere/lattice/blob/main/Agents/PairedEvaluation.cs) (Paired Evaluation), [`Agents/External/ExternalAgent.cs`](https://github.com/candavere/lattice/blob/main/Agents/External/ExternalAgent.cs) (External Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Simulation Runtime"]
  node_mapgen["Map Generation<br/>[MapGenerator.cs]"]
  node_environment["Map And Rules<br/>[MapData.cs]"]
  node_simulation["Step Simulation<br/>[Simulation.cs]"]
end

subgraph group_agents["Agents And Evaluation"]
  node_policies["Agent Policies<br/>[AgentFactories.cs]"]
  node_scenario["Scenario Runner<br/>[ScenarioRunner.cs]"]
  node_evaluation["Paired Evaluation"]
  node_benchmark["Benchmarking"]
  node_external["External Agent<br/>[ExternalAgent.cs]"]
  node_artifact["Evaluation Artifact<br/>[JsonArtifact.cs]"]
  node_throughput["Throughput Artifact<br/>[BenchmarkReport.cs]"]
end

subgraph group_recording["Trajectory Records"]
  node_writer["Trajectory Writer"]
  node_recordingfile["JSONL Recording<br/>[TrajectoryModel.cs]"]
  node_reader["Trajectory Reader"]
  node_replay["Replay Verification"]
end

subgraph group_insight["Analysis And Views"]
  node_analytics["Trajectory Analysis"]
  node_report["Analysis Report<br/>[ReportGenerator.cs]"]
  node_render["Trajectory Rendering"]
  node_viewer["Browser Viewer<br/>[app.js]"]
end

subgraph group_interface["CLI And Protocol"]
  node_cli["Command App<br/>[CliApp.cs]"]
  node_protocol["Wire Protocol<br/>[ProtocolParser.cs]"]
end

node_user(("Researcher"))
node_process(("Agent Process"))

node_user -->|"runs commands"| node_cli
node_cli -->|"generates maps"| node_mapgen
node_mapgen -->|"provides map"| node_environment
node_cli -->|"runs simulation"| node_scenario
node_scenario -->|"steps state"| node_simulation
node_scenario -->|"requests actions"| node_policies
node_policies -->|"returns actions"| node_simulation
node_scenario -->|"records run"| node_writer
node_writer -->|"writes JSONL"| node_recordingfile
node_cli -->|"loads recording"| node_reader
node_reader -->|"reads JSONL"| node_recordingfile
node_cli -->|"verifies replay"| node_replay
node_replay -->|"recomputes steps"| node_simulation
node_cli -->|"renders recording"| node_render
node_cli -->|"analyzes recording"| node_analytics
node_analytics -->|"feeds report"| node_report
node_user -->|"opens viewer"| node_viewer
node_viewer -.->|"reads recording"| node_recordingfile
node_cli -->|"runs evaluation"| node_evaluation
node_evaluation -->|"runs paired scenarios"| node_scenario
node_evaluation -->|"writes result"| node_artifact
node_cli -->|"runs benchmark"| node_benchmark
node_benchmark -->|"writes metrics"| node_throughput
node_evaluation -.->|"seats candidate"| node_external
node_external -->|"exchanges messages"| node_protocol
node_external -->|"launches process"| node_process
node_process -->|"speaks protocol"| node_protocol

click node_cli "https://github.com/candavere/lattice/blob/main/Cli/CliApp.cs"
click node_mapgen "https://github.com/candavere/lattice/blob/main/Generator/MapGenerator.cs"
click node_environment "https://github.com/candavere/lattice/blob/main/Environment/MapData.cs"
click node_simulation "https://github.com/candavere/lattice/blob/main/Environment/Simulation.cs"
click node_policies "https://github.com/candavere/lattice/blob/main/Agents/AgentFactories.cs"
click node_scenario "https://github.com/candavere/lattice/blob/main/Agents/ScenarioRunner.cs"
click node_evaluation "https://github.com/candavere/lattice/blob/main/Agents/PairedEvaluation.cs"
click node_benchmark "https://github.com/candavere/lattice/blob/main/Analytics/Benchmarking/BenchmarkHarness.cs"
click node_external "https://github.com/candavere/lattice/blob/main/Agents/External/ExternalAgent.cs"
click node_protocol "https://github.com/candavere/lattice/blob/main/Protocol/ProtocolParser.cs"
click node_writer "https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryWriter.cs"
click node_recordingfile "https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryModel.cs"
click node_reader "https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryReader.cs"
click node_replay "https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryReplay.cs"
click node_analytics "https://github.com/candavere/lattice/blob/main/Analytics/TrajectoryAnalyzer.cs"
click node_report "https://github.com/candavere/lattice/blob/main/Analytics/ReportGenerator.cs"
click node_render "https://github.com/candavere/lattice/blob/main/Visualization/SvgTrajectoryExporter.cs"
click node_viewer "https://github.com/candavere/lattice/blob/main/site/app.js"
click node_artifact "https://github.com/candavere/lattice/blob/main/Cli/JsonArtifact.cs"
click node_throughput "https://github.com/candavere/lattice/blob/main/Analytics/Benchmarking/BenchmarkReport.cs"

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_mapgen,node_environment,node_simulation toneBlue
class node_policies,node_scenario,node_evaluation,node_benchmark,node_external,node_artifact,node_throughput toneAmber
class node_writer,node_recordingfile,node_reader,node_replay toneMint
class node_analytics,node_report,node_render,node_viewer toneRose
class node_cli,node_protocol,node_user,node_process toneIndigo
```

## Components

### Simulation Runtime

- [Map Generation](https://github.com/candavere/lattice/blob/main/Generator/MapGenerator.cs): `Generator/MapGenerator.cs`
- [Map And Rules](https://github.com/candavere/lattice/blob/main/Environment/MapData.cs): `Environment/MapData.cs`
- [Step Simulation](https://github.com/candavere/lattice/blob/main/Environment/Simulation.cs): `Environment/Simulation.cs`

### Agents And Evaluation

- [Agent Policies](https://github.com/candavere/lattice/blob/main/Agents/AgentFactories.cs): `Agents/AgentFactories.cs`
- [Scenario Runner](https://github.com/candavere/lattice/blob/main/Agents/ScenarioRunner.cs): `Agents/ScenarioRunner.cs`
- [Paired Evaluation](https://github.com/candavere/lattice/blob/main/Agents/PairedEvaluation.cs): `Agents/PairedEvaluation.cs`
- [Benchmarking](https://github.com/candavere/lattice/blob/main/Analytics/Benchmarking/BenchmarkHarness.cs): `Analytics/Benchmarking/BenchmarkHarness.cs`
- [External Agent](https://github.com/candavere/lattice/blob/main/Agents/External/ExternalAgent.cs): `Agents/External/ExternalAgent.cs`
- [Evaluation Artifact](https://github.com/candavere/lattice/blob/main/Cli/JsonArtifact.cs): `Cli/JsonArtifact.cs`
- [Throughput Artifact](https://github.com/candavere/lattice/blob/main/Analytics/Benchmarking/BenchmarkReport.cs): `Analytics/Benchmarking/BenchmarkReport.cs`

### Trajectory Records

- [Trajectory Writer](https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryWriter.cs): `Trajectories/TrajectoryWriter.cs`
- [JSONL Recording](https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryModel.cs): `Trajectories/TrajectoryModel.cs`
- [Trajectory Reader](https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryReader.cs): `Trajectories/TrajectoryReader.cs`
- [Replay Verification](https://github.com/candavere/lattice/blob/main/Trajectories/TrajectoryReplay.cs): `Trajectories/TrajectoryReplay.cs`

### Analysis And Views

- [Trajectory Analysis](https://github.com/candavere/lattice/blob/main/Analytics/TrajectoryAnalyzer.cs): `Analytics/TrajectoryAnalyzer.cs`
- [Analysis Report](https://github.com/candavere/lattice/blob/main/Analytics/ReportGenerator.cs): `Analytics/ReportGenerator.cs`
- [Trajectory Rendering](https://github.com/candavere/lattice/blob/main/Visualization/SvgTrajectoryExporter.cs): `Visualization/SvgTrajectoryExporter.cs`
- [Browser Viewer](https://github.com/candavere/lattice/blob/main/site/app.js): `site/app.js`

### CLI And Protocol

- [Command App](https://github.com/candavere/lattice/blob/main/Cli/CliApp.cs): `Cli/CliApp.cs`
- [Wire Protocol](https://github.com/candavere/lattice/blob/main/Protocol/ProtocolParser.cs): `Protocol/ProtocolParser.cs`

### Other components

- **Researcher**
- **Agent Process**

## Connections

- Researcher → Command App: runs commands
- Command App → Map Generation: generates maps
- Map Generation → Map And Rules: provides map
- Command App → Scenario Runner: runs simulation
- Scenario Runner → Step Simulation: steps state
- Scenario Runner → Agent Policies: requests actions
- Agent Policies → Step Simulation: returns actions
- Scenario Runner → Trajectory Writer: records run
- Trajectory Writer → JSONL Recording: writes JSONL
- Command App → Trajectory Reader: loads recording
- Trajectory Reader → JSONL Recording: reads JSONL
- Command App → Replay Verification: verifies replay
- Replay Verification → Step Simulation: recomputes steps
- Command App → Trajectory Rendering: renders recording
- Command App → Trajectory Analysis: analyzes recording
- Trajectory Analysis → Analysis Report: feeds report
- Researcher → Browser Viewer: opens viewer
- Browser Viewer → JSONL Recording: reads recording
- Command App → Paired Evaluation: runs evaluation
- Paired Evaluation → Scenario Runner: runs paired scenarios
- Paired Evaluation → Evaluation Artifact: writes result
- Command App → Benchmarking: runs benchmark
- Benchmarking → Throughput Artifact: writes metrics
- Paired Evaluation → External Agent: seats candidate
- External Agent → Wire Protocol: exchanges messages
- External Agent → Agent Process: launches process
- Agent Process → Wire Protocol: speaks protocol