# voightxyz/mavlink-bridge architecture

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

- Interactive diagram: https://gitdiagram.com/voightxyz/mavlink-bridge
- Repository: https://github.com/voightxyz/mavlink-bridge

## Overview

MAVLink Bridge runs an ArduPilot inspection mission: the bridge starts or connects to SITL, the mission executive commands flight over MAVLink, and the agent evaluates telemetry and applies safety rules at each decision. GNSS/EKF integrity handling can switch navigation and trigger return-to-base. Mission events stream to Voight, while a local server exposes live state to the 3D ground-station view. README documents several runtime capabilities whose internal implementation is only partly sampled; those links are cited to the README.

Main entry points: [`src/main.ts`](https://github.com/voightxyz/mavlink-bridge/blob/main/src/main.ts) (Mission orchestrator), [`src/mav.ts`](https://github.com/voightxyz/mavlink-bridge/blob/main/src/mav.ts) (MAVLink transport), [`src/vehicle.ts`](https://github.com/voightxyz/mavlink-bridge/blob/main/src/vehicle.ts) (Mission executive), [`src/server.ts`](https://github.com/voightxyz/mavlink-bridge/blob/main/src/server.ts) (State and web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mission["Mission control"]
  node_main["Mission orchestrator<br/>[main.ts]"]
  node_sitl["SITL launcher<br/>[sitl.ts]"]
  node_site["Site and mission data<br/>[site.ts]"]
end

subgraph group_flight["Flight and integrity"]
  node_executive["Mission executive<br/>[vehicle.ts]"]
  node_agent["Agent and safety rules<br/>[agent.ts]"]
  node_spoof["GNSS spoof staging<br/>[spoof.ts]"]
  node_mav["MAVLink transport<br/>[mav.ts]"]
end

subgraph group_visibility["Monitoring and trace"]
  node_voight["Voight event client<br/>[voight.ts]"]
  node_webserver["State and web server<br/>[server.ts]"]
  node_dashboard["3D ground station<br/>[app.js]"]
end

subgraph group_external["External systems"]
  node_autopilot{{"ArduPilot SITL"}}
  node_llm{{"OpenAI-compatible model"}}
end

node_operator(("Mission operator"))
node_browser(("Ground-station user"))

node_operator -->|"starts mission"| node_main
node_main -->|"starts SITL"| node_sitl
node_main -->|"runs mission"| node_executive
node_main -->|"requests decisions"| node_agent
node_main -->|"stages fault"| node_spoof
node_executive -->|"uses site geometry"| node_site
node_executive -->|"sends flight commands"| node_mav
node_agent -->|"reads telemetry"| node_executive
node_agent -->|"requests tool choice"| node_llm
node_main -->|"configures telemetry"| node_mav
node_spoof -->|"sets simulated GNSS fault"| node_mav
node_sitl -->|"launches"| node_autopilot
node_mav -->|"sends MAVLink"| node_autopilot
node_autopilot -->|"returns telemetry and acknowledgements"| node_mav
node_main -->|"emits mission events"| node_voight
node_main -->|"provides state and restart"| node_webserver
node_webserver -->|"serves dashboard assets"| node_dashboard
node_browser -->|"opens ground station"| node_webserver
node_webserver -->|"streams vehicle state"| node_dashboard

click node_main "https://github.com/voightxyz/mavlink-bridge/blob/main/src/main.ts"
click node_sitl "https://github.com/voightxyz/mavlink-bridge/blob/main/src/sitl.ts"
click node_site "https://github.com/voightxyz/mavlink-bridge/blob/main/src/site.ts"
click node_executive "https://github.com/voightxyz/mavlink-bridge/blob/main/src/vehicle.ts"
click node_agent "https://github.com/voightxyz/mavlink-bridge/blob/main/src/agent.ts"
click node_spoof "https://github.com/voightxyz/mavlink-bridge/blob/main/src/spoof.ts"
click node_mav "https://github.com/voightxyz/mavlink-bridge/blob/main/src/mav.ts"
click node_voight "https://github.com/voightxyz/mavlink-bridge/blob/main/src/voight.ts"
click node_webserver "https://github.com/voightxyz/mavlink-bridge/blob/main/src/server.ts"
click node_dashboard "https://github.com/voightxyz/mavlink-bridge/blob/main/public/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_main,node_sitl,node_site,node_browser toneBlue
class node_executive,node_agent,node_spoof,node_mav toneAmber
class node_voight,node_webserver,node_dashboard toneMint
class node_autopilot,node_llm toneRose
class node_operator toneIndigo
```

## Components

### Mission control

- [Mission orchestrator](https://github.com/voightxyz/mavlink-bridge/blob/main/src/main.ts): `src/main.ts`
- [SITL launcher](https://github.com/voightxyz/mavlink-bridge/blob/main/src/sitl.ts): `src/sitl.ts`
- [Site and mission data](https://github.com/voightxyz/mavlink-bridge/blob/main/src/site.ts): `src/site.ts`

### Flight and integrity

- [Mission executive](https://github.com/voightxyz/mavlink-bridge/blob/main/src/vehicle.ts): `src/vehicle.ts`
- [Agent and safety rules](https://github.com/voightxyz/mavlink-bridge/blob/main/src/agent.ts): `src/agent.ts`
- [GNSS spoof staging](https://github.com/voightxyz/mavlink-bridge/blob/main/src/spoof.ts): `src/spoof.ts`
- [MAVLink transport](https://github.com/voightxyz/mavlink-bridge/blob/main/src/mav.ts): `src/mav.ts`

### Monitoring and trace

- [Voight event client](https://github.com/voightxyz/mavlink-bridge/blob/main/src/voight.ts): `src/voight.ts`
- [State and web server](https://github.com/voightxyz/mavlink-bridge/blob/main/src/server.ts): `src/server.ts`
- [3D ground station](https://github.com/voightxyz/mavlink-bridge/blob/main/public/app.js): `public/app.js`

### External systems

- **ArduPilot SITL**
- **OpenAI-compatible model**

### Other components

- **Mission operator**
- **Ground-station user**

## Connections

- Mission operator → Mission orchestrator: starts mission (evidence: `README.md`)
- Mission orchestrator → SITL launcher: starts SITL (evidence: `README.md`)
- Mission orchestrator → Mission executive: runs mission (evidence: `src/main.ts`)
- Mission orchestrator → Agent and safety rules: requests decisions (evidence: `src/main.ts`)
- Mission orchestrator → GNSS spoof staging: stages fault (evidence: `README.md`)
- Mission executive → Site and mission data: uses site geometry (evidence: `src/vehicle.ts`)
- Mission executive → MAVLink transport: sends flight commands (evidence: `src/vehicle.ts`)
- Agent and safety rules → Mission executive: reads telemetry (evidence: `src/agent.ts`)
- Agent and safety rules → OpenAI-compatible model: requests tool choice (evidence: `README.md`)
- Mission orchestrator → MAVLink transport: configures telemetry (evidence: `src/main.ts`)
- GNSS spoof staging → MAVLink transport: sets simulated GNSS fault (evidence: `README.md`)
- SITL launcher → ArduPilot SITL: launches (evidence: `src/sitl.ts`)
- MAVLink transport → ArduPilot SITL: sends MAVLink (evidence: `README.md`)
- ArduPilot SITL → MAVLink transport: returns telemetry and acknowledgements (evidence: `README.md`)
- Mission orchestrator → Voight event client: emits mission events (evidence: `src/main.ts`)
- Mission orchestrator → State and web server: provides state and restart (evidence: `src/main.ts`)
- State and web server → 3D ground station: serves dashboard assets (evidence: `src/server.ts`)
- Ground-station user → State and web server: opens ground station (evidence: `README.md`)
- State and web server → 3D ground station: streams vehicle state (evidence: `README.md`)
