# reeper316099/outbreakscope architecture

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

- Interactive diagram: https://gitdiagram.com/reeper316099/outbreakscope
- Repository: https://github.com/reeper316099/outbreakscope

## Overview

OutbreakScope is a desktop teaching app for exploring infectious-disease scenarios, stochastic variation, and parameter fitting to case data. Users configure a model and timed interventions in the simulator, inspect derived curves and ensemble results, or import observations and run an optimizer followed by parallel MCMC chains. The renderer coordinates workers and file workflows; Electron provides the desktop shell and guarded IPC. The graph preserves README-described charting, comparison, explanation, import/export, and diagnostics capabilities. Unsampled UI and simulation modules are included by exact tree path; their detailed internal calls are not inferred.

Main entry points: [`src/ui/simulator.ts`](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/simulator.ts) (Scenario controls), [`src/sim/fitRun.ts`](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/fitRun.ts) (Fit orchestration), [`src/ui/fitView.ts`](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/fitView.ts) (Fit workspace), [`src/sim/stochastic.ts`](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/stochastic.ts) (Stochastic models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop shell"]
  node_shell["Electron shell<br/>[main.ts]"]
  node_ipc["Native IPC<br/>[ipc.ts]"]
end

subgraph group_experience["Scenario experience"]
  node_bootstrap["Renderer router<br/>[main.ts]"]
  node_simui["Scenario controls<br/>[simulator.ts]"]
  node_charts["Charts and results<br/>[resultsPanel.ts]"]
  node_compare["Scenario comparison<br/>[compare.ts]"]
  node_explainer["Model explainer<br/>[explainer.ts]"]
  node_workers["Ensemble client<br/>[ensembleClient.ts]"]
end

subgraph group_simulation["Simulation engine"]
  node_ensembleworker["Ensemble worker<br/>[ensemble.worker.ts]"]
  node_ensemble["Stochastic ensemble<br/>[ensemble.ts]"]
  node_stochastic["Stochastic models<br/>[stochastic.ts]"]
  node_rk4["ODE integration<br/>[rk4.ts]"]
  node_models["Compartment models<br/>[models.ts]"]
  node_interventions["Intervention schedule<br/>[interventions.ts]"]
  node_derived["Derived metrics<br/>[derived.ts]"]
  node_rng["Seeded random<br/>[rng.ts]"]
  node_params["Parameter conversion<br/>[params.ts]"]
end

subgraph group_fitting["Data fitting"]
  node_fitview["Fit workspace<br/>[fitView.ts]"]
  node_fitclient["Fit coordinator<br/>[fitClient.ts]"]
  node_fitworker["Optimizer worker<br/>[fit.worker.ts]"]
  node_mcmcworker["Chain workers<br/>[mcmc.worker.ts]"]
  node_fitrun["Fit orchestration<br/>[fitRun.ts]"]
  node_fit["Fit evaluator<br/>[fit.ts]"]
  node_optimize["Nelder-Mead<br/>[optimize.ts]"]
  node_mcmc["MCMC sampler<br/>[mcmc.ts]"]
  node_diagnostics["Fit diagnostics<br/>[diagnostics.ts]"]
end

subgraph group_data["Data and contracts"]
  node_csv["CSV import<br/>[csv.ts]"]
  node_datasets["Bundled datasets<br/>[datasets.ts]"]
  node_export["Data export<br/>[export.ts]"]
  node_session["Scenario sessions<br/>[session.ts]"]
  node_storage[("Preferences storage<br/>[storage.ts]")]
  node_schema["Runtime schemas<br/>[schemas.ts]"]
  node_types["Shared contracts<br/>[types.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_bootstrap
node_bootstrap -->|"routes to"| node_simui
node_bootstrap -->|"routes to"| node_fitview
node_simui -->|"starts runs"| node_workers
node_workers -->|"dispatches"| node_ensembleworker
node_ensembleworker -->|"runs"| node_stochastic
node_ensemble -->|"aggregates"| node_stochastic
node_stochastic -->|"uses grid"| node_rk4
node_rk4 -->|"builds rates"| node_models
node_rk4 -->|"selects segment"| node_interventions
node_stochastic -->|"selects segment"| node_interventions
node_simui -.->|"renders results"| node_charts
node_simui -->|"supports overlays"| node_compare
node_bootstrap -->|"routes to"| node_explainer
node_fitview -->|"parses imports"| node_csv
node_fitview -->|"loads samples"| node_datasets
node_fitview -->|"starts fit"| node_fitclient
node_fitclient -->|"optimizes first"| node_fitworker
node_fitclient -->|"launches chains"| node_mcmcworker
node_fitworker -->|"runs fit stage"| node_fitrun
node_mcmcworker -->|"runs chain stage"| node_fitrun
node_fitrun -->|"evaluates model"| node_fit
node_fitrun -->|"calls optimizer"| node_optimize
node_fitrun -->|"samples chains"| node_mcmc
node_fitrun -->|"computes diagnostics"| node_diagnostics
node_fit -->|"simulates cases"| node_rk4
node_fit -->|"checks identifiability"| node_diagnostics
node_simui -->|"saves scenarios"| node_session
node_simui -->|"exports results"| node_export
node_fitview -->|"exports fit"| node_export
node_shell -->|"registers"| node_ipc
node_ipc -->|"validates requests"| node_schema
node_session -->|"validates files"| node_schema
node_storage -->|"validates preferences"| node_schema
node_ensembleworker -->|"seeds realizations"| node_rng
node_stochastic -->|"draws events"| node_rng
node_rk4 -->|"sets step rates"| node_params

click node_shell "https://github.com/reeper316099/outbreakscope/blob/main/electron/main.ts"
click node_ipc "https://github.com/reeper316099/outbreakscope/blob/main/electron/ipc.ts"
click node_bootstrap "https://github.com/reeper316099/outbreakscope/blob/main/src/main.ts"
click node_simui "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/simulator.ts"
click node_charts "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/resultsPanel.ts"
click node_compare "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/compare.ts"
click node_explainer "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/explainer.ts"
click node_workers "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/ensembleClient.ts"
click node_ensembleworker "https://github.com/reeper316099/outbreakscope/blob/main/src/workers/ensemble.worker.ts"
click node_ensemble "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/ensemble.ts"
click node_stochastic "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/stochastic.ts"
click node_rk4 "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/rk4.ts"
click node_models "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/models.ts"
click node_interventions "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/interventions.ts"
click node_derived "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/derived.ts"
click node_fitview "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/fitView.ts"
click node_csv "https://github.com/reeper316099/outbreakscope/blob/main/src/io/csv.ts"
click node_datasets "https://github.com/reeper316099/outbreakscope/blob/main/src/io/datasets.ts"
click node_fitclient "https://github.com/reeper316099/outbreakscope/blob/main/src/ui/fitClient.ts"
click node_fitworker "https://github.com/reeper316099/outbreakscope/blob/main/src/workers/fit.worker.ts"
click node_mcmcworker "https://github.com/reeper316099/outbreakscope/blob/main/src/workers/mcmc.worker.ts"
click node_fitrun "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/fitRun.ts"
click node_fit "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/fit.ts"
click node_optimize "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/optimize.ts"
click node_mcmc "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/mcmc.ts"
click node_diagnostics "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/diagnostics.ts"
click node_export "https://github.com/reeper316099/outbreakscope/blob/main/src/io/export.ts"
click node_session "https://github.com/reeper316099/outbreakscope/blob/main/src/io/session.ts"
click node_storage "https://github.com/reeper316099/outbreakscope/blob/main/src/io/storage.ts"
click node_schema "https://github.com/reeper316099/outbreakscope/blob/main/src/shared/schemas.ts"
click node_types "https://github.com/reeper316099/outbreakscope/blob/main/src/shared/types.ts"
click node_rng "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/rng.ts"
click node_params "https://github.com/reeper316099/outbreakscope/blob/main/src/sim/params.ts"

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_shell,node_ipc,node_user toneBlue
class node_bootstrap,node_simui,node_charts,node_compare,node_explainer,node_workers toneAmber
class node_ensembleworker,node_ensemble,node_stochastic,node_rk4,node_models,node_interventions,node_derived,node_rng,node_params toneMint
class node_fitview,node_fitclient,node_fitworker,node_mcmcworker,node_fitrun,node_fit,node_optimize,node_mcmc,node_diagnostics toneRose
class node_csv,node_datasets,node_export,node_session,node_storage,node_schema,node_types toneIndigo
```

## Components

### Desktop shell

- [Electron shell](https://github.com/reeper316099/outbreakscope/blob/main/electron/main.ts): `electron/main.ts`
- [Native IPC](https://github.com/reeper316099/outbreakscope/blob/main/electron/ipc.ts): `electron/ipc.ts`

### Scenario experience

- [Renderer router](https://github.com/reeper316099/outbreakscope/blob/main/src/main.ts): `src/main.ts`
- [Scenario controls](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/simulator.ts): `src/ui/simulator.ts`
- [Charts and results](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/resultsPanel.ts): `src/ui/resultsPanel.ts`
- [Scenario comparison](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/compare.ts): `src/ui/compare.ts`
- [Model explainer](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/explainer.ts): `src/ui/explainer.ts`
- [Ensemble client](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/ensembleClient.ts): `src/ui/ensembleClient.ts`

### Simulation engine

- [Ensemble worker](https://github.com/reeper316099/outbreakscope/blob/main/src/workers/ensemble.worker.ts): `src/workers/ensemble.worker.ts`
- [Stochastic ensemble](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/ensemble.ts): `src/sim/ensemble.ts`
- [Stochastic models](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/stochastic.ts): `src/sim/stochastic.ts`
- [ODE integration](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/rk4.ts): `src/sim/rk4.ts`
- [Compartment models](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/models.ts): `src/sim/models.ts`
- [Intervention schedule](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/interventions.ts): `src/sim/interventions.ts`
- [Derived metrics](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/derived.ts): `src/sim/derived.ts`
- [Seeded random](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/rng.ts): `src/sim/rng.ts`
- [Parameter conversion](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/params.ts): `src/sim/params.ts`

### Data fitting

- [Fit workspace](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/fitView.ts): `src/ui/fitView.ts`
- [Fit coordinator](https://github.com/reeper316099/outbreakscope/blob/main/src/ui/fitClient.ts): `src/ui/fitClient.ts`
- [Optimizer worker](https://github.com/reeper316099/outbreakscope/blob/main/src/workers/fit.worker.ts): `src/workers/fit.worker.ts`
- [Chain workers](https://github.com/reeper316099/outbreakscope/blob/main/src/workers/mcmc.worker.ts): `src/workers/mcmc.worker.ts`
- [Fit orchestration](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/fitRun.ts): `src/sim/fitRun.ts`
- [Fit evaluator](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/fit.ts): `src/sim/fit.ts`
- [Nelder-Mead](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/optimize.ts): `src/sim/optimize.ts`
- [MCMC sampler](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/mcmc.ts): `src/sim/mcmc.ts`
- [Fit diagnostics](https://github.com/reeper316099/outbreakscope/blob/main/src/sim/diagnostics.ts): `src/sim/diagnostics.ts`

### Data and contracts

- [CSV import](https://github.com/reeper316099/outbreakscope/blob/main/src/io/csv.ts): `src/io/csv.ts`
- [Bundled datasets](https://github.com/reeper316099/outbreakscope/blob/main/src/io/datasets.ts): `src/io/datasets.ts`
- [Data export](https://github.com/reeper316099/outbreakscope/blob/main/src/io/export.ts): `src/io/export.ts`
- [Scenario sessions](https://github.com/reeper316099/outbreakscope/blob/main/src/io/session.ts): `src/io/session.ts`
- [Preferences storage](https://github.com/reeper316099/outbreakscope/blob/main/src/io/storage.ts): `src/io/storage.ts`
- [Runtime schemas](https://github.com/reeper316099/outbreakscope/blob/main/src/shared/schemas.ts): `src/shared/schemas.ts`
- [Shared contracts](https://github.com/reeper316099/outbreakscope/blob/main/src/shared/types.ts): `src/shared/types.ts`

### Other components

- **User**

## Connections

- User → Renderer router: uses (evidence: `src/main.ts`)
- Renderer router → Scenario controls: routes to (evidence: `src/main.ts`)
- Renderer router → Fit workspace: routes to (evidence: `src/main.ts`)
- Scenario controls → Ensemble client: starts runs (evidence: `src/ui/simulator.ts`)
- Ensemble client → Ensemble worker: dispatches (evidence: `src/ui/ensembleClient.ts`)
- Ensemble worker → Stochastic models: runs (evidence: `src/workers/ensemble.worker.ts`)
- Stochastic ensemble → Stochastic models: aggregates (evidence: `src/sim/ensemble.ts`)
- Stochastic models → ODE integration: uses grid (evidence: `src/sim/stochastic.ts`)
- ODE integration → Compartment models: builds rates (evidence: `src/sim/rk4.ts`)
- ODE integration → Intervention schedule: selects segment (evidence: `src/sim/rk4.ts`)
- Stochastic models → Intervention schedule: selects segment (evidence: `src/sim/stochastic.ts`)
- Scenario controls → Charts and results: renders results (evidence: `src/ui/simulator.ts`)
- Scenario controls → Scenario comparison: supports overlays (evidence: `src/ui/simulator.ts`)
- Renderer router → Model explainer: routes to (evidence: `src/main.ts`)
- Fit workspace → CSV import: parses imports (evidence: `src/ui/fitView.ts`)
- Fit workspace → Bundled datasets: loads samples (evidence: `src/ui/fitView.ts`)
- Fit workspace → Fit coordinator: starts fit (evidence: `src/ui/fitView.ts`)
- Fit coordinator → Optimizer worker: optimizes first (evidence: `src/ui/fitClient.ts`)
- Fit coordinator → Chain workers: launches chains (evidence: `src/ui/fitClient.ts`)
- Optimizer worker → Fit orchestration: runs fit stage (evidence: `src/workers/fit.worker.ts`)
- Chain workers → Fit orchestration: runs chain stage (evidence: `src/workers/mcmc.worker.ts`)
- Fit orchestration → Fit evaluator: evaluates model (evidence: `src/sim/fitRun.ts`)
- Fit orchestration → Nelder-Mead: calls optimizer (evidence: `src/sim/fitRun.ts`)
- Fit orchestration → MCMC sampler: samples chains (evidence: `src/sim/fitRun.ts`)
- Fit orchestration → Fit diagnostics: computes diagnostics (evidence: `src/sim/fitRun.ts`)
- Fit evaluator → ODE integration: simulates cases (evidence: `src/sim/fit.ts`)
- Fit evaluator → Fit diagnostics: checks identifiability (evidence: `src/sim/fit.ts`)
- Scenario controls → Scenario sessions: saves scenarios (evidence: `src/ui/simulator.ts`)
- Scenario controls → Data export: exports results (evidence: `src/ui/simulator.ts`)
- Fit workspace → Data export: exports fit (evidence: `src/ui/fitView.ts`)
- Electron shell → Native IPC: registers (evidence: `electron/main.ts`)
- Native IPC → Runtime schemas: validates requests (evidence: `electron/ipc.ts`)
- Scenario sessions → Runtime schemas: validates files (evidence: `src/io/session.ts`)
- Preferences storage → Runtime schemas: validates preferences (evidence: `src/io/storage.ts`)
- Ensemble worker → Seeded random: seeds realizations (evidence: `src/workers/ensemble.worker.ts`)
- Stochastic models → Seeded random: draws events (evidence: `src/sim/stochastic.ts`)
- ODE integration → Parameter conversion: sets step rates (evidence: `src/sim/rk4.ts`)