# nitin3560/uav-swarm-security architecture

> Architecture diagram of the GitHub repository nitin3560/uav-swarm-security, 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/uav-swarm-security
- Repository: https://github.com/nitin3560/uav-swarm-security

## Overview

This repository implements UAV-swarm security simulation and a related ISAC digital-twin synchronisation study. The primary simulation workflow advances swarm dynamics, injects faults and attacks, estimates twin state, detects and attributes anomalies, applies a trust-weighted MPC correction, and tracks the resulting references. A separate Paper 3 workflow replays synthetic or real sensing data and evaluates HOLD/FUSE/SYNC policies. The main workflow is documented in the README; some runner internals and ISAC modules were not sampled, so those links are limited to documented or indexed relationships.

Main entry points: [`run_study.py`](https://github.com/nitin3560/uav-swarm-security/blob/main/run_study.py) (Scenario runner), [`isac_dt_sync_v3.py`](https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_v3.py) (DeepSense sync), [`run_matrix.py`](https://github.com/nitin3560/uav-swarm-security/blob/main/run_matrix.py) (Seed matrix), [`trust_mpc.py`](https://github.com/nitin3560/uav-swarm-security/blob/main/trust_mpc.py) (Trust MPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sim["Swarm simulation"]
  node_runner["Scenario runner<br/>[run_study.py]"]
  node_matrix["Seed matrix<br/>[run_matrix.py]"]
  node_dynamics["Swarm dynamics<br/>[env.py]"]
  node_faults["Fault injection<br/>[faults.py]"]
  node_attacks["Attack injection"]
  node_trajectory["Swarm trajectory<br/>[trajectory.py]"]
end

subgraph group_security["Detection and control"]
  node_twin["Digital twin<br/>[digital_twin.py]"]
  node_ids["Intrusion detector<br/>[ids.py]"]
  node_diagnosis["Fault diagnosis<br/>[diagnosis.py]"]
  node_supervisor["Supervisory control<br/>[controllers.py]"]
  node_mpc["Trust MPC<br/>[trust_mpc.py]"]
  node_tracking["PID tracking<br/>[controllers.py]"]
  node_metrics["Security metrics"]
end

subgraph group_replay["ISAC replay"]
  node_euroc["EuRoC replay<br/>[euroc_replay.py]"]
  node_aerpaw["AERPAW replay"]
  node_aerpaw2["Gated radar replay"]
  node_realreplay["Real-channel replay"]
end

subgraph group_sync["Twin synchronisation"]
  node_syncv2["Synthetic sync study<br/>[isac_dt_sync_v2.py]"]
  node_syncv3["DeepSense sync<br/>[isac_dt_sync_v3.py]"]
  node_synca["AERPAW sync"]
end

node_operator(("Study operator"))

node_operator -->|"runs scenario"| node_runner
node_operator -->|"runs seeds"| node_matrix
node_matrix -->|"orchestrates runs"| node_runner
node_runner -->|"advances state"| node_dynamics
node_runner -->|"injects faults"| node_faults
node_runner -->|"injects attacks"| node_attacks
node_runner -->|"updates estimate"| node_twin
node_runner -->|"detects anomalies"| node_ids
node_runner -.->|"coordinates diagnosis"| node_diagnosis
node_runner -.->|"selects control"| node_supervisor
node_runner -->|"requests correction"| node_mpc
node_runner -->|"tracks references"| node_tracking
node_runner -.->|"uses reference path"| node_trajectory
node_runner -.->|"records outcomes"| node_metrics
node_mpc -->|"reads IDS output"| node_ids
node_operator -->|"replays dataset"| node_euroc
node_operator -->|"replays radar"| node_aerpaw
node_aerpaw2 -->|"extends adapter"| node_aerpaw
node_operator -->|"replays channel"| node_realreplay
node_operator -->|"evaluates policies"| node_syncv2
node_operator -->|"evaluates real data"| node_syncv3
node_syncv3 -->|"loads channel data"| node_realreplay
node_syncv3 -->|"uses filter helpers"| node_euroc
node_operator -->|"runs radar sync"| node_synca
node_synca -->|"consumes radar stream"| node_aerpaw2

click node_runner "https://github.com/nitin3560/uav-swarm-security/blob/main/run_study.py"
click node_matrix "https://github.com/nitin3560/uav-swarm-security/blob/main/run_matrix.py"
click node_dynamics "https://github.com/nitin3560/uav-swarm-security/blob/main/env.py"
click node_faults "https://github.com/nitin3560/uav-swarm-security/blob/main/faults.py"
click node_attacks "https://github.com/nitin3560/uav-swarm-security/blob/main/attack_injection.py"
click node_twin "https://github.com/nitin3560/uav-swarm-security/blob/main/digital_twin.py"
click node_ids "https://github.com/nitin3560/uav-swarm-security/blob/main/ids.py"
click node_diagnosis "https://github.com/nitin3560/uav-swarm-security/blob/main/diagnosis.py"
click node_supervisor "https://github.com/nitin3560/uav-swarm-security/blob/main/controllers.py"
click node_mpc "https://github.com/nitin3560/uav-swarm-security/blob/main/trust_mpc.py"
click node_tracking "https://github.com/nitin3560/uav-swarm-security/blob/main/controllers.py"
click node_trajectory "https://github.com/nitin3560/uav-swarm-security/blob/main/trajectory.py"
click node_metrics "https://github.com/nitin3560/uav-swarm-security/blob/main/security_metrics.py"
click node_euroc "https://github.com/nitin3560/uav-swarm-security/blob/main/euroc_replay.py"
click node_aerpaw "https://github.com/nitin3560/uav-swarm-security/blob/main/aerpaw_radar_replay.py"
click node_aerpaw2 "https://github.com/nitin3560/uav-swarm-security/blob/main/aerpaw_radar_replay_v2.py"
click node_realreplay "https://github.com/nitin3560/uav-swarm-security/blob/main/real_isac_replay.py"
click node_syncv2 "https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_v2.py"
click node_syncv3 "https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_v3.py"
click node_synca "https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_aerpaw.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_runner,node_matrix,node_dynamics,node_faults,node_attacks,node_trajectory toneBlue
class node_twin,node_ids,node_diagnosis,node_supervisor,node_mpc,node_tracking,node_metrics toneAmber
class node_euroc,node_aerpaw,node_aerpaw2,node_realreplay toneMint
class node_syncv2,node_syncv3,node_synca toneRose
class node_operator toneIndigo
```

## Components

### Swarm simulation

- [Scenario runner](https://github.com/nitin3560/uav-swarm-security/blob/main/run_study.py): `run_study.py`
- [Seed matrix](https://github.com/nitin3560/uav-swarm-security/blob/main/run_matrix.py): `run_matrix.py`
- [Swarm dynamics](https://github.com/nitin3560/uav-swarm-security/blob/main/env.py): `env.py`
- [Fault injection](https://github.com/nitin3560/uav-swarm-security/blob/main/faults.py): `faults.py`
- [Attack injection](https://github.com/nitin3560/uav-swarm-security/blob/main/attack_injection.py): `attack_injection.py`
- [Swarm trajectory](https://github.com/nitin3560/uav-swarm-security/blob/main/trajectory.py): `trajectory.py`

### Detection and control

- [Digital twin](https://github.com/nitin3560/uav-swarm-security/blob/main/digital_twin.py): `digital_twin.py`
- [Intrusion detector](https://github.com/nitin3560/uav-swarm-security/blob/main/ids.py): `ids.py`
- [Fault diagnosis](https://github.com/nitin3560/uav-swarm-security/blob/main/diagnosis.py): `diagnosis.py`
- [Supervisory control](https://github.com/nitin3560/uav-swarm-security/blob/main/controllers.py): `controllers.py`
- [Trust MPC](https://github.com/nitin3560/uav-swarm-security/blob/main/trust_mpc.py): `trust_mpc.py`
- [PID tracking](https://github.com/nitin3560/uav-swarm-security/blob/main/controllers.py): `controllers.py`
- [Security metrics](https://github.com/nitin3560/uav-swarm-security/blob/main/security_metrics.py): `security_metrics.py`

### ISAC replay

- [EuRoC replay](https://github.com/nitin3560/uav-swarm-security/blob/main/euroc_replay.py): `euroc_replay.py`
- [AERPAW replay](https://github.com/nitin3560/uav-swarm-security/blob/main/aerpaw_radar_replay.py): `aerpaw_radar_replay.py`
- [Gated radar replay](https://github.com/nitin3560/uav-swarm-security/blob/main/aerpaw_radar_replay_v2.py): `aerpaw_radar_replay_v2.py`
- [Real-channel replay](https://github.com/nitin3560/uav-swarm-security/blob/main/real_isac_replay.py): `real_isac_replay.py`

### Twin synchronisation

- [Synthetic sync study](https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_v2.py): `isac_dt_sync_v2.py`
- [DeepSense sync](https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_v3.py): `isac_dt_sync_v3.py`
- [AERPAW sync](https://github.com/nitin3560/uav-swarm-security/blob/main/isac_dt_sync_aerpaw.py): `isac_dt_sync_aerpaw.py`

### Other components

- **Study operator**

## Connections

- Study operator → Scenario runner: runs scenario (evidence: `README.md`)
- Study operator → Seed matrix: runs seeds (evidence: `README.md`)
- Seed matrix → Scenario runner: orchestrates runs (evidence: `README.md`)
- Scenario runner → Swarm dynamics: advances state (evidence: `README.md`)
- Scenario runner → Fault injection: injects faults (evidence: `README.md`)
- Scenario runner → Attack injection: injects attacks (evidence: `README.md`)
- Scenario runner → Digital twin: updates estimate (evidence: `README.md`)
- Scenario runner → Intrusion detector: detects anomalies (evidence: `README.md`)
- Scenario runner → Fault diagnosis: coordinates diagnosis
- Scenario runner → Supervisory control: selects control
- Scenario runner → Trust MPC: requests correction (evidence: `README.md`)
- Scenario runner → PID tracking: tracks references (evidence: `README.md`)
- Scenario runner → Swarm trajectory: uses reference path
- Scenario runner → Security metrics: records outcomes
- Trust MPC → Intrusion detector: reads IDS output (evidence: `trust_mpc.py`)
- Study operator → EuRoC replay: replays dataset (evidence: `euroc_replay.py`)
- Study operator → AERPAW replay: replays radar (evidence: `aerpaw_radar_replay.py`)
- Gated radar replay → AERPAW replay: extends adapter (evidence: `aerpaw_radar_replay_v2.py`)
- Study operator → Real-channel replay: replays channel (evidence: `real_isac_replay.py`)
- Study operator → Synthetic sync study: evaluates policies (evidence: `isac_dt_sync_v2.py`)
- Study operator → DeepSense sync: evaluates real data (evidence: `isac_dt_sync_v3.py`)
- DeepSense sync → Real-channel replay: loads channel data (evidence: `isac_dt_sync_v3.py`)
- DeepSense sync → EuRoC replay: uses filter helpers (evidence: `isac_dt_sync_v3.py`)
- Study operator → AERPAW sync: runs radar sync (evidence: `isac_dt_sync_aerpaw.py`)
- AERPAW sync → Gated radar replay: consumes radar stream (evidence: `README.md`)
