# foamyfsky/branchlab architecture

> Architecture diagram of the GitHub repository foamyfsky/branchlab, 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/foamyfsky/branchlab
- Repository: https://github.com/foamyfsky/branchlab

## Overview

BranchLab is a deterministic three-room particle-control research dashboard. The main workflow is to create an experiment, advance and intervene on a cleaner, fork named branches, then compare completed outcomes or export a replay record. A separate batch workflow evaluates fixed placement schedules and writes a CSV. The README documents additional dashboard views and evaluation capabilities; the excerpts do not expose every UI handler, so uncertain internal wiring is omitted.

Main entry points: [`app.py`](https://github.com/foamyfsky/branchlab/blob/main/app.py) (Streamlit dashboard), [`src/branchlab/session.py`](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py) (Experiment session), [`src/branchlab/experiment.py`](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/experiment.py) (Batch evaluation), [`src/branchlab/transport.py`](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/transport.py) (Piecewise transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Interactive dashboard"]
  node_dashboard_app["Streamlit dashboard<br/>[app.py]"]
  node_experiment_view["Experiment controls<br/>[app.py]"]
  node_compare_view["Branch comparisons<br/>[app.py]"]
end

subgraph group_experiments["Experiment sessions"]
  node_session["Experiment session<br/>[session.py]"]
  node_branch_state["Branch state<br/>[session.py]"]
  node_replay_record["Versioned replay<br/>[session.py]"]
  node_worked_example["Worked example"]
end

subgraph group_model["Transport model"]
  node_transport["Piecewise transport<br/>[transport.py]"]
  node_exact_solver["Exact propagation<br/>[transport.py]"]
end

subgraph group_evaluation["Schedule evaluation"]
  node_batch_evaluation["Batch evaluation<br/>[experiment.py]"]
  node_schedule_search["Schedule comparison<br/>[experiment.py]"]
  node_csv_results["Evaluation results<br/>[transport.csv]"]
  node_result_directory["Evaluation figures"]
end

node_user(("Research user"))
node_streamlit{{"Streamlit runtime"}}
node_plotly{{"Plotly charts"}}

node_user -->|"uses"| node_dashboard_app
node_dashboard_app -->|"renders"| node_experiment_view
node_dashboard_app -->|"renders"| node_compare_view
node_dashboard_app -->|"creates and updates"| node_session
node_experiment_view -->|"controls"| node_session
node_compare_view -->|"reads summaries"| node_session
node_dashboard_app -.->|"loads"| node_worked_example
node_dashboard_app -->|"imports and exports"| node_replay_record
node_session -->|"manages"| node_branch_state
node_session -->|"advances state"| node_transport
node_session -->|"validates and replays"| node_replay_record
node_transport -->|"propagates with"| node_exact_solver
node_batch_evaluation -->|"evaluates"| node_schedule_search
node_batch_evaluation -->|"simulates schedules"| node_transport
node_batch_evaluation -->|"writes"| node_csv_results
node_batch_evaluation -->|"writes figure"| node_result_directory
node_dashboard_app -->|"runs on"| node_streamlit
node_dashboard_app -->|"renders charts with"| node_plotly

click node_dashboard_app "https://github.com/foamyfsky/branchlab/blob/main/app.py"
click node_experiment_view "https://github.com/foamyfsky/branchlab/blob/main/app.py"
click node_compare_view "https://github.com/foamyfsky/branchlab/blob/main/app.py"
click node_session "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py"
click node_branch_state "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py"
click node_replay_record "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py"
click node_worked_example "https://github.com/foamyfsky/branchlab/blob/main/examples/cleaner-relocation.json"
click node_transport "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/transport.py"
click node_exact_solver "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/transport.py"
click node_batch_evaluation "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/experiment.py"
click node_schedule_search "https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/experiment.py"
click node_csv_results "https://github.com/foamyfsky/branchlab/blob/main/results/transport.csv"
click node_result_directory "https://github.com/foamyfsky/branchlab/tree/main/results"

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_dashboard_app,node_experiment_view,node_compare_view,node_user toneBlue
class node_session,node_branch_state,node_replay_record,node_worked_example toneAmber
class node_transport,node_exact_solver toneMint
class node_batch_evaluation,node_schedule_search,node_csv_results,node_result_directory toneRose
class node_streamlit,node_plotly toneIndigo
```

## Components

### Interactive dashboard

- [Streamlit dashboard](https://github.com/foamyfsky/branchlab/blob/main/app.py): `app.py`
- [Experiment controls](https://github.com/foamyfsky/branchlab/blob/main/app.py): `app.py`
- [Branch comparisons](https://github.com/foamyfsky/branchlab/blob/main/app.py): `app.py`

### Experiment sessions

- [Experiment session](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py): `src/branchlab/session.py`
- [Branch state](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py): `src/branchlab/session.py`
- [Versioned replay](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/session.py): `src/branchlab/session.py`
- [Worked example](https://github.com/foamyfsky/branchlab/blob/main/examples/cleaner-relocation.json): `examples/cleaner-relocation.json`

### Transport model

- [Piecewise transport](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/transport.py): `src/branchlab/transport.py`
- [Exact propagation](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/transport.py): `src/branchlab/transport.py`

### Schedule evaluation

- [Batch evaluation](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/experiment.py): `src/branchlab/experiment.py`
- [Schedule comparison](https://github.com/foamyfsky/branchlab/blob/main/src/branchlab/experiment.py): `src/branchlab/experiment.py`
- [Evaluation results](https://github.com/foamyfsky/branchlab/blob/main/results/transport.csv): `results/transport.csv`
- [Evaluation figures](https://github.com/foamyfsky/branchlab/tree/main/results): `results`

### Other components

- **Research user**
- **Streamlit runtime**
- **Plotly charts**

## Connections

- Research user → Streamlit dashboard: uses
- Streamlit dashboard → Experiment controls: renders
- Streamlit dashboard → Branch comparisons: renders
- Streamlit dashboard → Experiment session: creates and updates
- Experiment controls → Experiment session: controls
- Branch comparisons → Experiment session: reads summaries
- Streamlit dashboard → Worked example: loads
- Streamlit dashboard → Versioned replay: imports and exports
- Experiment session → Branch state: manages
- Experiment session → Piecewise transport: advances state
- Experiment session → Versioned replay: validates and replays
- Piecewise transport → Exact propagation: propagates with
- Batch evaluation → Schedule comparison: evaluates
- Batch evaluation → Piecewise transport: simulates schedules
- Batch evaluation → Evaluation results: writes
- Batch evaluation → Evaluation figures: writes figure
- Streamlit dashboard → Streamlit runtime: runs on
- Streamlit dashboard → Plotly charts: renders charts with