# loicz/mosaic architecture

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

- Interactive diagram: https://gitdiagram.com/loicz/mosaic
- Repository: https://github.com/loicz/mosaic
- Video tour (about a minute): https://gitdiagram.com/loicz/mosaic/video

## Overview

MOSAIC simulates an emergency-personnel localization mission: a user launches a PX4/Gazebo scenario, drones deploy and form a ranging network, personnel are tracked indoors and through evacuation, and the fleet can be recalled. The graph preserves the documented autonomy, mapping, coverage, fault, replay, and console capabilities. Some modules are indexed but unsampled; their paths are included, but uncertain runtime links are omitted. Edges reflect shown references or README workflow statements.

Main entry points: [`scripts/mission_runtime.py`](https://github.com/loicz/mosaic/blob/main/scripts/mission_runtime.py) (Mission coordinator), [`dashboard/mission/app.js`](https://github.com/loicz/mosaic/blob/main/dashboard/mission/app.js) (Browser console), [`scripts/mission_run.py`](https://github.com/loicz/mosaic/blob/main/scripts/mission_run.py) (Mission launcher), [`scripts/mission_agent.py`](https://github.com/loicz/mosaic/blob/main/scripts/mission_agent.py) (Onboard drone agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coord["Mission coordination"]
  node_launcher["Mission launcher<br/>[mission_run.py]"]
  node_environment["Isolated runtime<br/>[mission_env.py]"]
  node_coordinator["Mission coordinator<br/>[mission_runtime.py]"]
  node_radio["UWB radio<br/>[mission_radio.py]"]
  node_link["Command link<br/>[mission_link.py]"]
  node_coverage["Route coverage"]
  node_replay["Session replay<br/>[mission_replay.py]"]
  node_packaging["Runtime packaging<br/>[mission_package.py]"]
end

subgraph group_autonomy["Drone autonomy"]
  node_sitl["SITL integration<br/>[mission_sitl.py]"]
  node_world["Simulation world<br/>[mission_world.py]"]
  node_agent["Onboard drone agent<br/>[mission_agent.py]"]
  node_mapping["Lidar mapping<br/>[mission_mapping.py]"]
  node_inference["Local inference<br/>[mission_compute.py]"]
  node_power["Power model<br/>[mission_power.py]"]
  node_training["Model training<br/>[mission_train.py]"]
end

subgraph group_localization["Localization engine"]
  node_engine["Mission algorithms<br/>[mission.cpp]"]
  node_compute_cli["Compute CLI"]
end

subgraph group_console["Mission console"]
  node_dashboard["Browser console<br/>[app.js]"]
  node_freshness["Data freshness<br/>[freshness.mjs]"]
  node_map["3D map view<br/>[map-view.mjs]"]
  node_trail["Trail segments<br/>[trail-segments.mjs]"]
  node_labels["Console text<br/>[ui-text.mjs]"]
end

node_operator(("Operator"))
node_simulator["PX4 / Gazebo"]

node_operator -->|"launches"| node_launcher
node_launcher -->|"runs within"| node_environment
node_launcher -->|"starts"| node_coordinator
node_launcher -->|"uses"| node_replay
node_coordinator -->|"dispatches"| node_agent
node_coordinator -->|"checks"| node_coverage
node_coordinator -->|"uses"| node_radio
node_coordinator -->|"uses"| node_link
node_agent -->|"uses"| node_inference
node_agent -->|"uses"| node_mapping
node_sitl -->|"uses"| node_world
node_dashboard -->|"validates"| node_freshness
node_dashboard -->|"renders"| node_map
node_dashboard -->|"formats"| node_labels
node_map -->|"draws"| node_trail
node_dashboard -.->|"tracks mission"| node_coordinator
node_coordinator -.->|"controls"| node_simulator
node_agent -.->|"flies in"| node_simulator

click node_launcher "https://github.com/loicz/mosaic/blob/main/scripts/mission_run.py"
click node_environment "https://github.com/loicz/mosaic/blob/main/scripts/mission_env.py"
click node_coordinator "https://github.com/loicz/mosaic/blob/main/scripts/mission_runtime.py"
click node_radio "https://github.com/loicz/mosaic/blob/main/scripts/mission_radio.py"
click node_link "https://github.com/loicz/mosaic/blob/main/scripts/mission_link.py"
click node_coverage "https://github.com/loicz/mosaic/blob/main/scripts/mission_coverage.py"
click node_replay "https://github.com/loicz/mosaic/blob/main/scripts/mission_replay.py"
click node_packaging "https://github.com/loicz/mosaic/blob/main/scripts/mission_package.py"
click node_sitl "https://github.com/loicz/mosaic/blob/main/scripts/mission_sitl.py"
click node_world "https://github.com/loicz/mosaic/blob/main/scripts/mission_world.py"
click node_agent "https://github.com/loicz/mosaic/blob/main/scripts/mission_agent.py"
click node_mapping "https://github.com/loicz/mosaic/blob/main/scripts/mission_mapping.py"
click node_inference "https://github.com/loicz/mosaic/blob/main/scripts/mission_compute.py"
click node_power "https://github.com/loicz/mosaic/blob/main/scripts/mission_power.py"
click node_training "https://github.com/loicz/mosaic/blob/main/scripts/mission_train.py"
click node_engine "https://github.com/loicz/mosaic/blob/main/src/mission.cpp"
click node_compute_cli "https://github.com/loicz/mosaic/blob/main/apps/mission_compute.cpp"
click node_dashboard "https://github.com/loicz/mosaic/blob/main/dashboard/mission/app.js"
click node_freshness "https://github.com/loicz/mosaic/blob/main/dashboard/mission/freshness.mjs"
click node_map "https://github.com/loicz/mosaic/blob/main/dashboard/mission/map-view.mjs"
click node_trail "https://github.com/loicz/mosaic/blob/main/dashboard/mission/trail-segments.mjs"
click node_labels "https://github.com/loicz/mosaic/blob/main/dashboard/mission/ui-text.mjs"

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_launcher,node_environment,node_coordinator,node_radio,node_link,node_coverage,node_replay,node_packaging toneBlue
class node_sitl,node_world,node_agent,node_mapping,node_inference,node_power,node_training toneAmber
class node_engine,node_compute_cli toneMint
class node_dashboard,node_freshness,node_map,node_trail,node_labels toneRose
class node_operator,node_simulator toneIndigo
```

## Components

### Mission coordination

- [Mission launcher](https://github.com/loicz/mosaic/blob/main/scripts/mission_run.py): `scripts/mission_run.py`
- [Isolated runtime](https://github.com/loicz/mosaic/blob/main/scripts/mission_env.py): `scripts/mission_env.py`
- [Mission coordinator](https://github.com/loicz/mosaic/blob/main/scripts/mission_runtime.py): `scripts/mission_runtime.py`
- [UWB radio](https://github.com/loicz/mosaic/blob/main/scripts/mission_radio.py): `scripts/mission_radio.py`
- [Command link](https://github.com/loicz/mosaic/blob/main/scripts/mission_link.py): `scripts/mission_link.py`
- [Route coverage](https://github.com/loicz/mosaic/blob/main/scripts/mission_coverage.py): `scripts/mission_coverage.py`
- [Session replay](https://github.com/loicz/mosaic/blob/main/scripts/mission_replay.py): `scripts/mission_replay.py`
- [Runtime packaging](https://github.com/loicz/mosaic/blob/main/scripts/mission_package.py): `scripts/mission_package.py`

### Drone autonomy

- [SITL integration](https://github.com/loicz/mosaic/blob/main/scripts/mission_sitl.py): `scripts/mission_sitl.py`
- [Simulation world](https://github.com/loicz/mosaic/blob/main/scripts/mission_world.py): `scripts/mission_world.py`
- [Onboard drone agent](https://github.com/loicz/mosaic/blob/main/scripts/mission_agent.py): `scripts/mission_agent.py`
- [Lidar mapping](https://github.com/loicz/mosaic/blob/main/scripts/mission_mapping.py): `scripts/mission_mapping.py`
- [Local inference](https://github.com/loicz/mosaic/blob/main/scripts/mission_compute.py): `scripts/mission_compute.py`
- [Power model](https://github.com/loicz/mosaic/blob/main/scripts/mission_power.py): `scripts/mission_power.py`
- [Model training](https://github.com/loicz/mosaic/blob/main/scripts/mission_train.py): `scripts/mission_train.py`

### Localization engine

- [Mission algorithms](https://github.com/loicz/mosaic/blob/main/src/mission.cpp): `src/mission.cpp`
- [Compute CLI](https://github.com/loicz/mosaic/blob/main/apps/mission_compute.cpp): `apps/mission_compute.cpp`

### Mission console

- [Browser console](https://github.com/loicz/mosaic/blob/main/dashboard/mission/app.js): `dashboard/mission/app.js`
- [Data freshness](https://github.com/loicz/mosaic/blob/main/dashboard/mission/freshness.mjs): `dashboard/mission/freshness.mjs`
- [3D map view](https://github.com/loicz/mosaic/blob/main/dashboard/mission/map-view.mjs): `dashboard/mission/map-view.mjs`
- [Trail segments](https://github.com/loicz/mosaic/blob/main/dashboard/mission/trail-segments.mjs): `dashboard/mission/trail-segments.mjs`
- [Console text](https://github.com/loicz/mosaic/blob/main/dashboard/mission/ui-text.mjs): `dashboard/mission/ui-text.mjs`

### Other components

- **Operator**
- **PX4 / Gazebo**

## Connections

- Operator → Mission launcher: launches (evidence: `README.md`)
- Mission launcher → Isolated runtime: runs within (evidence: `scripts/mission_run.py`)
- Mission launcher → Mission coordinator: starts (evidence: `scripts/mission_run.py`)
- Mission launcher → Session replay: uses (evidence: `scripts/mission_run.py`)
- Mission coordinator → Onboard drone agent: dispatches (evidence: `scripts/mission_runtime.py`)
- Mission coordinator → Route coverage: checks (evidence: `scripts/mission_runtime.py`)
- Mission coordinator → UWB radio: uses (evidence: `scripts/mission_runtime.py`)
- Mission coordinator → Command link: uses (evidence: `scripts/mission_runtime.py`)
- Onboard drone agent → Local inference: uses (evidence: `scripts/mission_agent.py`)
- Onboard drone agent → Lidar mapping: uses (evidence: `scripts/mission_agent.py`)
- SITL integration → Simulation world: uses (evidence: `scripts/mission_sitl.py`)
- Browser console → Data freshness: validates (evidence: `dashboard/mission/app.js`)
- Browser console → 3D map view: renders (evidence: `dashboard/mission/app.js`)
- Browser console → Console text: formats (evidence: `dashboard/mission/app.js`)
- 3D map view → Trail segments: draws (evidence: `dashboard/mission/map-view.mjs`)
- Browser console → Mission coordinator: tracks mission (evidence: `README.md`)
- Mission coordinator → PX4 / Gazebo: controls (evidence: `README.md`)
- Onboard drone agent → PX4 / Gazebo: flies in (evidence: `README.md`)
