# akitaengineering/meshswarm architecture

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

- Interactive diagram: https://gitdiagram.com/akitaengineering/meshswarm
- Repository: https://github.com/akitaengineering/meshswarm

## Overview

MeshSwarm pairs a web ground-control station with ESP32 companion firmware to exchange encrypted telemetry and commands over Meshtastic, then translate aircraft commands to MAVLink. The main operator path is browser control or telemetry view → GCS API and radio → mesh framing/encryption → companion validation and command handling → MAVLink flight controller; telemetry returns through the GCS receive path to map/API and JSONL log. README also documents signed key provisioning, replay protection, ACK retries, and aircraft fail-safes. Firmware internals are partly unsampled, so only documented relationships are shown where source calls were not excerpted.

Main entry points: [`main/main.cpp`](https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp) (ESP32 runtime), [`gcs_app.py`](https://github.com/akitaengineering/meshswarm/blob/main/gcs_app.py) (GCS app), [`meshtastic_telemetry.py`](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_telemetry.py) (Telemetry receive), [`meshtastic_control.py`](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_control.py) (Control and ACKs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gcs["Ground control"]
  node_webui["Map UI<br/>[index.html]"]
  node_gcsapp["GCS app<br/>[gcs_app.py]"]
  node_radio["Meshtastic radio"]
  node_telem["Telemetry receive"]
  node_control["Control and ACKs"]
  node_log[("Telemetry JSONL")]
  node_sim["Fake radio<br/>[qa_simulator.py]"]
end

subgraph group_wire["Mesh protocol"]
  node_crypto["Crypto and sequence"]
  node_framepy["Python frame codec<br/>[mesh_frame.py]"]
end

subgraph group_firmware["Companion firmware"]
  node_companion["ESP32 runtime<br/>[main.cpp]"]
  node_mcodec["Meshtastic UART codec<br/>[mesh_codec.cpp]"]
  node_mframe["Firmware frame codec<br/>[mesh_frame.cpp]"]
  node_provision["Signed provisioning<br/>[main.cpp]"]
  node_provisionkey["Provisioning public key"]
end

subgraph group_aircraft["Aircraft and safety"]
  node_failsafe["Failsafe evaluator<br/>[failsafe.cpp]"]
  node_mavruntime["MAVLink runtime<br/>[main.cpp]"]
  node_mavcodec["MAVLink codec<br/>[mavlink_min.cpp]"]
end

node_operator(("Operator"))
node_fc["Flight controller"]
node_meshnet(("Meshtastic mesh"))

node_operator -->|"operates"| node_webui
node_webui -->|"calls API"| node_gcsapp
node_gcsapp -->|"dispatches commands"| node_control
node_gcsapp -->|"reads snapshots"| node_telem
node_gcsapp -->|"sends and receives"| node_radio
node_gcsapp -->|"selects fake radio"| node_sim
node_control -->|"encrypts and sequences"| node_crypto
node_telem -->|"decrypts telemetry"| node_crypto
node_control -->|"frames commands"| node_framepy
node_telem -->|"decodes frames"| node_framepy
node_telem -->|"appends records"| node_log
node_radio -->|"transmits packets"| node_meshnet
node_meshnet -->|"delivers over UART"| node_mcodec
node_companion -->|"polls and sends"| node_mcodec
node_companion -->|"encodes and decodes"| node_mframe
node_companion -->|"handles key setup"| node_provision
node_provision -->|"verifies signatures"| node_provisionkey
node_companion -->|"evaluates conditions"| node_failsafe
node_companion -->|"handles aircraft state"| node_mavruntime
node_mavruntime -->|"packs and parses"| node_mavcodec
node_mavruntime -->|"commands and reads state"| node_fc
node_companion -->|"uses mesh link"| node_meshnet
node_sim -->|"fires telemetry"| node_telem
node_sim -->|"returns ACKs"| node_control

click node_webui "https://github.com/akitaengineering/meshswarm/blob/main/templates/index.html"
click node_gcsapp "https://github.com/akitaengineering/meshswarm/blob/main/gcs_app.py"
click node_telem "https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_telemetry.py"
click node_control "https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_control.py"
click node_crypto "https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_crypto.py"
click node_framepy "https://github.com/akitaengineering/meshswarm/blob/main/mesh_frame.py"
click node_log "https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_telemetry.py"
click node_sim "https://github.com/akitaengineering/meshswarm/blob/main/qa_simulator.py"
click node_companion "https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp"
click node_mcodec "https://github.com/akitaengineering/meshswarm/blob/main/main/mesh_codec.cpp"
click node_mframe "https://github.com/akitaengineering/meshswarm/blob/main/main/mesh_frame.cpp"
click node_provision "https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp"
click node_provisionkey "https://github.com/akitaengineering/meshswarm/blob/main/provisioning_pubkey.h"
click node_failsafe "https://github.com/akitaengineering/meshswarm/blob/main/main/failsafe.cpp"
click node_mavruntime "https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp"
click node_mavcodec "https://github.com/akitaengineering/meshswarm/blob/main/main/mavlink_min.cpp"

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_webui,node_gcsapp,node_radio,node_telem,node_control,node_log,node_sim toneBlue
class node_crypto,node_framepy toneAmber
class node_companion,node_mcodec,node_mframe,node_provision,node_provisionkey toneMint
class node_failsafe,node_mavruntime,node_mavcodec toneRose
class node_operator,node_fc,node_meshnet toneIndigo
```

## Components

### Ground control

- [Map UI](https://github.com/akitaengineering/meshswarm/blob/main/templates/index.html): `templates/index.html`
- [GCS app](https://github.com/akitaengineering/meshswarm/blob/main/gcs_app.py): `gcs_app.py`
- **Meshtastic radio**
- [Telemetry receive](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_telemetry.py): `meshtastic_telemetry.py`
- [Control and ACKs](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_control.py): `meshtastic_control.py`
- [Telemetry JSONL](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_telemetry.py): `meshtastic_telemetry.py`
- [Fake radio](https://github.com/akitaengineering/meshswarm/blob/main/qa_simulator.py): `qa_simulator.py`

### Mesh protocol

- [Crypto and sequence](https://github.com/akitaengineering/meshswarm/blob/main/meshtastic_crypto.py): `meshtastic_crypto.py`
- [Python frame codec](https://github.com/akitaengineering/meshswarm/blob/main/mesh_frame.py): `mesh_frame.py`

### Companion firmware

- [ESP32 runtime](https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp): `main/main.cpp`
- [Meshtastic UART codec](https://github.com/akitaengineering/meshswarm/blob/main/main/mesh_codec.cpp): `main/mesh_codec.cpp`
- [Firmware frame codec](https://github.com/akitaengineering/meshswarm/blob/main/main/mesh_frame.cpp): `main/mesh_frame.cpp`
- [Signed provisioning](https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp): `main/main.cpp`
- [Provisioning public key](https://github.com/akitaengineering/meshswarm/blob/main/provisioning_pubkey.h): `provisioning_pubkey.h`

### Aircraft and safety

- [Failsafe evaluator](https://github.com/akitaengineering/meshswarm/blob/main/main/failsafe.cpp): `main/failsafe.cpp`
- [MAVLink runtime](https://github.com/akitaengineering/meshswarm/blob/main/main/main.cpp): `main/main.cpp`
- [MAVLink codec](https://github.com/akitaengineering/meshswarm/blob/main/main/mavlink_min.cpp): `main/mavlink_min.cpp`

### Other components

- **Operator**
- **Flight controller**
- **Meshtastic mesh**

## Connections

- Operator → Map UI: operates (evidence: `README.md`)
- Map UI → GCS app: calls API (evidence: `README.md`)
- GCS app → Control and ACKs: dispatches commands (evidence: `gcs_app.py`)
- GCS app → Telemetry receive: reads snapshots (evidence: `gcs_app.py`)
- GCS app → Meshtastic radio: sends and receives (evidence: `gcs_app.py`)
- GCS app → Fake radio: selects fake radio (evidence: `gcs_app.py`)
- Control and ACKs → Crypto and sequence: encrypts and sequences (evidence: `meshtastic_control.py`)
- Telemetry receive → Crypto and sequence: decrypts telemetry (evidence: `meshtastic_telemetry.py`)
- Control and ACKs → Python frame codec: frames commands (evidence: `meshtastic_control.py`)
- Telemetry receive → Python frame codec: decodes frames (evidence: `meshtastic_telemetry.py`)
- Telemetry receive → Telemetry JSONL: appends records (evidence: `meshtastic_telemetry.py`)
- Meshtastic radio → Meshtastic mesh: transmits packets (evidence: `README.md`)
- Meshtastic mesh → Meshtastic UART codec: delivers over UART (evidence: `README.md`)
- ESP32 runtime → Meshtastic UART codec: polls and sends (evidence: `main/main.cpp`)
- ESP32 runtime → Firmware frame codec: encodes and decodes (evidence: `main/main.cpp`)
- ESP32 runtime → Signed provisioning: handles key setup (evidence: `README.md`)
- Signed provisioning → Provisioning public key: verifies signatures (evidence: `README.md`)
- ESP32 runtime → Failsafe evaluator: evaluates conditions (evidence: `main/main.cpp`)
- ESP32 runtime → MAVLink runtime: handles aircraft state (evidence: `README.md`)
- MAVLink runtime → MAVLink codec: packs and parses (evidence: `main/main.cpp`)
- MAVLink runtime → Flight controller: commands and reads state (evidence: `README.md`)
- ESP32 runtime → Meshtastic mesh: uses mesh link (evidence: `README.md`)
- Fake radio → Telemetry receive: fires telemetry (evidence: `qa_simulator.py`)
- Fake radio → Control and ACKs: returns ACKs (evidence: `qa_simulator.py`)
