# nitin3560/twinguard architecture

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

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

## Overview

TwinGuard is a ROS 2 trust-aware UAV autonomy framework. Its principal workflow fuses PX4 odometry (and visual-odometry diagnostics), evaluates localization integrity and authority, then exposes trust to planning and offboard supervision before commands reach PX4. Separate branches provide BehaviorTree/A* mission planning, Nav2 plugins, and dataset-driven replay with visualization. The graph combines sampled source relationships with README-documented runtime flow; unsampled wiring is not treated as inspected, and uncertain links are omitted.

Main entry points: [`ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp) (EKF Integrity Node), [`ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py`](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py) (Experiment Launches), [`ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp`](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp) (BehaviorTree Mission), [`ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp`](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp) (Formation Supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_estimation["Estimation &amp; Integrity"]
  node_ekfnode["EKF Integrity Node"]
  node_ekf["Kalman Estimator<br/>[ekf_estimator.cpp]"]
  node_authoritymodel["Estimation Authority"]
  node_vo["Visual Odometry"]
  node_trust["Trust Scoring<br/>[trust_scorer.cpp]"]
  node_safety["Hard Safety Monitor"]
  node_aggregator["Authority Aggregator"]
end

subgraph group_planning["Planning &amp; Navigation"]
  node_bt["BehaviorTree Mission<br/>[bt_nodes.cpp]"]
  node_astar["A* Planner<br/>[astar_planner.cpp]"]
  node_navcostmap["Integrity Costmap"]
  node_navcondition["Trust Condition"]
end

subgraph group_control["Control &amp; Supervision"]
  node_formation["Formation Supervisor"]
  node_offboard["Offboard Supervisor"]
end

subgraph group_validation["Replay &amp; Bringup"]
  node_replay["Dataset Replay"]
  node_visualizer["Trust Visualizer"]
  node_launch["Experiment Launches"]
end

node_operator(("Operator"))
node_px4["PX4 Vehicle"]
node_gazebo["Gazebo SITL"]

node_operator -->|"starts experiments"| node_launch
node_launch -->|"launches integrity"| node_ekfnode
node_px4 -->|"publishes odometry"| node_ekfnode
node_vo -->|"sends diagnostics"| node_ekfnode
node_ekfnode -->|"updates estimate"| node_ekf
node_ekfnode -->|"evaluates quality"| node_authoritymodel
node_ekfnode -->|"scores residual"| node_trust
node_ekfnode -->|"checks override"| node_safety
node_ekfnode -->|"aggregates factors"| node_aggregator
node_ekfnode -->|"publishes trust state"| node_navcostmap
node_ekfnode -->|"publishes trust state"| node_navcondition
node_ekfnode -->|"publishes trust state"| node_bt
node_bt -->|"plans reroutes"| node_astar
node_formation -->|"uses mission nodes"| node_bt
node_formation -->|"uses planner"| node_astar
node_bt -->|"provides setpoints"| node_offboard
node_offboard -->|"sends setpoints"| node_px4
node_navcostmap -.->|"guides navigation"| node_gazebo
node_replay -->|"replays degradation"| node_ekfnode
node_replay -.->|"provides replay data"| node_visualizer
node_launch -->|"launches replay"| node_replay
node_launch -->|"launches missions"| node_formation

click node_ekfnode "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp"
click node_ekf "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_estimator.cpp"
click node_authoritymodel "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/estimation_authority_model.cpp"
click node_vo "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/visual_odometry_node.cpp"
click node_trust "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/trust_scorer.cpp"
click node_safety "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/hard_safety_monitor.cpp"
click node_aggregator "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/authority_aggregator.cpp"
click node_bt "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp"
click node_astar "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_planning_cpp/src/astar_planner.cpp"
click node_navcostmap "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_nav2_cpp/src/integrity_costmap_layer.cpp"
click node_navcondition "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_nav2_cpp/src/is_agent_trustworthy.cpp"
click node_formation "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp"
click node_offboard "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/offboard_supervisor.cpp"
click node_replay "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/dataset_replay_node.py"
click node_visualizer "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/trust_visualizer_node.py"
click node_launch "https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py"

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_ekfnode,node_ekf,node_authoritymodel,node_vo,node_trust,node_safety,node_aggregator toneBlue
class node_bt,node_astar,node_navcostmap,node_navcondition toneAmber
class node_formation,node_offboard toneMint
class node_replay,node_visualizer,node_launch toneRose
class node_operator,node_px4,node_gazebo toneIndigo
```

## Components

### Estimation & Integrity

- [EKF Integrity Node](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp): `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`
- [Kalman Estimator](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_estimator.cpp): `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_estimator.cpp`
- [Estimation Authority](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/estimation_authority_model.cpp): `ros2_ws/src/twinguard_swarm_estimation_cpp/src/estimation_authority_model.cpp`
- [Visual Odometry](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_estimation_cpp/src/visual_odometry_node.cpp): `ros2_ws/src/twinguard_swarm_estimation_cpp/src/visual_odometry_node.cpp`
- [Trust Scoring](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/trust_scorer.cpp): `ros2_ws/src/twinguard_swarm_integrity_cpp/src/trust_scorer.cpp`
- [Hard Safety Monitor](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/hard_safety_monitor.cpp): `ros2_ws/src/twinguard_swarm_integrity_cpp/src/hard_safety_monitor.cpp`
- [Authority Aggregator](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/authority_aggregator.cpp): `ros2_ws/src/twinguard_swarm_integrity_cpp/src/authority_aggregator.cpp`

### Planning & Navigation

- [BehaviorTree Mission](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp): `ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp`
- [A* Planner](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_planning_cpp/src/astar_planner.cpp): `ros2_ws/src/twinguard_swarm_planning_cpp/src/astar_planner.cpp`
- [Integrity Costmap](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_nav2_cpp/src/integrity_costmap_layer.cpp): `ros2_ws/src/twinguard_swarm_nav2_cpp/src/integrity_costmap_layer.cpp`
- [Trust Condition](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_nav2_cpp/src/is_agent_trustworthy.cpp): `ros2_ws/src/twinguard_swarm_nav2_cpp/src/is_agent_trustworthy.cpp`

### Control & Supervision

- [Formation Supervisor](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp): `ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp`
- [Offboard Supervisor](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_integrity_cpp/src/offboard_supervisor.cpp): `ros2_ws/src/twinguard_swarm_integrity_cpp/src/offboard_supervisor.cpp`

### Replay & Bringup

- [Dataset Replay](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/dataset_replay_node.py): `ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/dataset_replay_node.py`
- [Trust Visualizer](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/trust_visualizer_node.py): `ros2_ws/src/twinguard_dataset_replay/twinguard_dataset_replay/trust_visualizer_node.py`
- [Experiment Launches](https://github.com/nitin3560/twinguard/blob/main/ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py): `ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py`

### Other components

- **Operator**
- **PX4 Vehicle**
- **Gazebo SITL**

## Connections

- Operator → Experiment Launches: starts experiments (evidence: `README.md`)
- Experiment Launches → EKF Integrity Node: launches integrity (evidence: `ros2_ws/src/twinguard_swarm_bringup/launch/twinguard_ekf_integrity.launch.py`)
- PX4 Vehicle → EKF Integrity Node: publishes odometry (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- Visual Odometry → EKF Integrity Node: sends diagnostics (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- EKF Integrity Node → Kalman Estimator: updates estimate (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- EKF Integrity Node → Estimation Authority: evaluates quality (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- EKF Integrity Node → Trust Scoring: scores residual (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- EKF Integrity Node → Hard Safety Monitor: checks override (evidence: `ros2_ws/src/twinguard_swarm_estimation_cpp/src/ekf_integrity_node.cpp`)
- EKF Integrity Node → Authority Aggregator: aggregates factors (evidence: `README.md`)
- EKF Integrity Node → Integrity Costmap: publishes trust state (evidence: `README.md`)
- EKF Integrity Node → Trust Condition: publishes trust state (evidence: `README.md`)
- EKF Integrity Node → BehaviorTree Mission: publishes trust state (evidence: `README.md`)
- BehaviorTree Mission → A* Planner: plans reroutes (evidence: `ros2_ws/src/twinguard_swarm_planning_cpp/src/bt_nodes.cpp`)
- Formation Supervisor → BehaviorTree Mission: uses mission nodes (evidence: `ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp`)
- Formation Supervisor → A* Planner: uses planner (evidence: `ros2_ws/src/twinguard_swarm_integrity_cpp/src/formation_supervisor_node.cpp`)
- BehaviorTree Mission → Offboard Supervisor: provides setpoints (evidence: `README.md`)
- Offboard Supervisor → PX4 Vehicle: sends setpoints (evidence: `README.md`)
- Integrity Costmap → Gazebo SITL: guides navigation
- Dataset Replay → EKF Integrity Node: replays degradation (evidence: `README.md`)
- Dataset Replay → Trust Visualizer: provides replay data
- Experiment Launches → Dataset Replay: launches replay
- Experiment Launches → Formation Supervisor: launches missions
