# dzentec/sia_sim architecture

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

## Overview

SIA Simulation is a deterministic 100 Hz yacht physics-and-sensor testbed for validating a safety core. The principal workflow configures a scenario, advances the simulated sea, vessel and sails, converts physical truth into an isolated SensorFrame, then evaluates SIA decisions against an independent oracle. The repository also provides an interactive workbench, sail advice and rig controls, and high-frequency run recording. The graph follows the README’s documented architecture and sampled entry points; some internal runner wiring and unsampled subsystem details are not shown.

Main entry points: [`src/sia_sim/engine/runner.py`](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/engine/runner.py) (Simulation Runner), [`src/sia_sim/workbench/server.py`](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/server.py) (Web Workbench), [`src/sia_sim/contracts/data.py`](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/contracts/data.py) (Ground Truth), [`src/sia_sim/workbench/static/js/app.js`](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/static/js/app.js) (Browser Cockpit)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation Core"]
  node_scenario["Scenario Setup<br/>[presets.py]"]
  node_clock_rng["Clock and RNG<br/>[clock.py]"]
  node_world["Sea Environment<br/>[world.py]"]
  node_dynamics["Vessel Dynamics<br/>[dynamics.py]"]
  node_sail_rig["3D Sail Rig<br/>[rig.py]"]
  node_runner["Simulation Runner<br/>[runner.py]"]
  node_ground_truth["Ground Truth<br/>[data.py]"]
end

subgraph group_sensing["Sensing and SIA"]
  node_sensor_pipeline["Sensor Pipeline<br/>[pipeline.py]"]
  node_sensor_frame["SensorFrame Contract<br/>[data.py]"]
  node_sia_core["SIA Core Adapter<br/>[mock_sia.py]"]
  node_sail_advisor["Sail Advisor<br/>[advisor.py]"]
end

subgraph group_validation["Validation and Records"]
  node_evaluator["Evaluator<br/>[evaluator.py]"]
  node_oracle["Oracle Engine<br/>[oracle.py]"]
  node_recorder[("Run Recorder<br/>[run_recorder.py]")]
end

subgraph group_controls["Workbench and Controls"]
  node_workbench["Web Workbench<br/>[server.py]"]
  node_websocket["Simulation API<br/>[server.py]"]
  node_rig_controller["Rig Controller<br/>[rig_controller.py]"]
  node_cockpit["Browser Cockpit<br/>[app.js]"]
end

node_skipper(("Skipper / Operator"))

node_skipper -->|"configures run"| node_workbench
node_workbench -->|"loads scenario"| node_scenario
node_workbench -->|"starts simulation"| node_runner
node_scenario -->|"configures"| node_runner
node_runner -->|"steps deterministically"| node_clock_rng
node_runner -->|"advances environment"| node_world
node_runner -->|"advances vessel"| node_dynamics
node_runner -->|"evaluates sails"| node_sail_rig
node_world -->|"contributes state"| node_ground_truth
node_dynamics -->|"contributes state"| node_ground_truth
node_sail_rig -->|"contributes forces"| node_ground_truth
node_runner -->|"supplies truth"| node_sensor_pipeline
node_ground_truth -->|"transforms"| node_sensor_pipeline
node_sensor_pipeline -->|"produces"| node_sensor_frame
node_runner -->|"provides observations"| node_sia_core
node_sensor_frame -->|"only input"| node_sia_core
node_sia_core -.->|"requests advice"| node_sail_advisor
node_runner -->|"submits run"| node_evaluator
node_runner -->|"submits truth"| node_oracle
node_runner -->|"records tick data"| node_recorder
node_evaluator -->|"compares outcome"| node_oracle
node_cockpit -->|"streams controls"| node_websocket
node_websocket -->|"steps and streams"| node_runner
node_cockpit -->|"configures run"| node_workbench
node_workbench -->|"submits rig commands"| node_rig_controller
node_rig_controller -->|"applies rig state"| node_sail_rig
node_skipper -->|"operates"| node_cockpit

click node_scenario "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/scenarios/presets.py"
click node_clock_rng "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/core/clock.py"
click node_world "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/world.py"
click node_dynamics "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/dynamics.py"
click node_sail_rig "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/sails/rig.py"
click node_runner "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/engine/runner.py"
click node_ground_truth "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/contracts/data.py"
click node_sensor_pipeline "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sensors/pipeline.py"
click node_sensor_frame "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/contracts/data.py"
click node_sia_core "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sia/mock_sia.py"
click node_sail_advisor "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sails/advisor.py"
click node_evaluator "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/evaluator/evaluator.py"
click node_oracle "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/evaluator/oracle.py"
click node_recorder "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/recorder/run_recorder.py"
click node_workbench "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/server.py"
click node_websocket "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/web/server.py"
click node_rig_controller "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/engine/rig_controller.py"
click node_cockpit "https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/static/js/app.js"

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_clock_rng,node_world,node_dynamics,node_sail_rig,node_runner,node_ground_truth toneBlue
class node_sensor_pipeline,node_sensor_frame,node_sia_core,node_sail_advisor toneAmber
class node_evaluator,node_oracle,node_recorder toneMint
class node_workbench,node_websocket,node_rig_controller,node_cockpit toneRose
class node_skipper toneIndigo
```

## Components

### Simulation Core

- [Scenario Setup](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/scenarios/presets.py): `src/sia_sim/scenarios/presets.py`
- [Clock and RNG](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/core/clock.py): `src/sia_sim/core/clock.py`
- [Sea Environment](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/world.py): `src/sia_sim/physics/world.py`
- [Vessel Dynamics](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/dynamics.py): `src/sia_sim/physics/dynamics.py`
- [3D Sail Rig](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/physics/sails/rig.py): `src/sia_sim/physics/sails/rig.py`
- [Simulation Runner](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/engine/runner.py): `src/sia_sim/engine/runner.py`
- [Ground Truth](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/contracts/data.py): `src/sia_sim/contracts/data.py`

### Sensing and SIA

- [Sensor Pipeline](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sensors/pipeline.py): `src/sia_sim/sensors/pipeline.py`
- [SensorFrame Contract](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/contracts/data.py): `src/sia_sim/contracts/data.py`
- [SIA Core Adapter](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sia/mock_sia.py): `src/sia_sim/sia/mock_sia.py`
- [Sail Advisor](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/sails/advisor.py): `src/sia_sim/sails/advisor.py`

### Validation and Records

- [Evaluator](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/evaluator/evaluator.py): `src/sia_sim/evaluator/evaluator.py`
- [Oracle Engine](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/evaluator/oracle.py): `src/sia_sim/evaluator/oracle.py`
- [Run Recorder](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/recorder/run_recorder.py): `src/sia_sim/recorder/run_recorder.py`

### Workbench and Controls

- [Web Workbench](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/server.py): `src/sia_sim/workbench/server.py`
- [Simulation API](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/web/server.py): `src/sia_sim/web/server.py`
- [Rig Controller](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/engine/rig_controller.py): `src/sia_sim/engine/rig_controller.py`
- [Browser Cockpit](https://github.com/dzentec/sia_sim/blob/master/src/sia_sim/workbench/static/js/app.js): `src/sia_sim/workbench/static/js/app.js`

### Other components

- **Skipper / Operator**

## Connections

- Skipper / Operator → Web Workbench: configures run
- Web Workbench → Scenario Setup: loads scenario
- Web Workbench → Simulation Runner: starts simulation
- Scenario Setup → Simulation Runner: configures
- Simulation Runner → Clock and RNG: steps deterministically
- Simulation Runner → Sea Environment: advances environment
- Simulation Runner → Vessel Dynamics: advances vessel
- Simulation Runner → 3D Sail Rig: evaluates sails
- Sea Environment → Ground Truth: contributes state
- Vessel Dynamics → Ground Truth: contributes state
- 3D Sail Rig → Ground Truth: contributes forces
- Simulation Runner → Sensor Pipeline: supplies truth
- Ground Truth → Sensor Pipeline: transforms
- Sensor Pipeline → SensorFrame Contract: produces
- Simulation Runner → SIA Core Adapter: provides observations
- SensorFrame Contract → SIA Core Adapter: only input
- SIA Core Adapter → Sail Advisor: requests advice
- Simulation Runner → Evaluator: submits run
- Simulation Runner → Oracle Engine: submits truth
- Simulation Runner → Run Recorder: records tick data
- Evaluator → Oracle Engine: compares outcome
- Browser Cockpit → Simulation API: streams controls
- Simulation API → Simulation Runner: steps and streams
- Browser Cockpit → Web Workbench: configures run
- Web Workbench → Rig Controller: submits rig commands
- Rig Controller → 3D Sail Rig: applies rig state
- Skipper / Operator → Browser Cockpit: operates