# shemayon/adids-advanced-drone-intrusion-detection-system-2026 architecture

> Architecture diagram of the GitHub repository shemayon/adids-advanced-drone-intrusion-detection-system-2026, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026
- Repository: https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026

## Overview

1. **What this repository is**
   A-DIDS is a drone-network intrusion detection system organized as a **flow-based ML pipeline**: network packets are captured or loaded from datasets, reconstructed into bidirectional flows, converted into feature vectors, scored by trained models, and optionally exposed through a FastAPI service.

2. **Core runtime path**
   The main production path is:
   **live packets or PCAP input → flow reconstruction → feature extraction → model inference → alert/API response**.
   The repo is built around keeping that path fast enough for real-time detection, with the trained model artifacts stored under `models/` and reused by inference components.

3. **Offline data engineering boundary**
   The offline side is centered on `data_pipeline.py`, `pcap_processor.py`, `modules/data_loader.py`, and the `data/` tree.
   This layer converts the ISOT Drone Dataset from raw captures and CSVs into model-ready features, likely normalizing the dataset into the 19-feature flow representation referenced in the README.

4. **Training and evaluation boundary**
   Model lifecycle is handled by `train_model.py`, `train_multiclass.py`, `benchmark_models.py`, `harden_model.py`, and validation scripts such as `validate_mixed_traffic.py`.
   This is where the XGBoost-based detector is trained, evaluated, benchmarked, and hardened, with outputs persisted as `model.pkl`, `model_multiclass.pkl`, and `model_hardened.pkl`.

5. **Online inference boundary**
   `inference_engine.py` appears to be the central scoring layer used by both the API and live sniffer.
   It is the boundary between feature vectors and predictions, returning class labels, confidence, and latency. This is the point where the system switches from packet handling to ML decisioning.

6. **Live capture and streaming ingestion**
   `live_sniffer.py` is the real-time capture front end.
   It uses Scapy-based packet sniffing to reconstruct bidirectional 5-tuple flows in a sliding window, then finalizes flows and immediately passes them into inference. This is the live operational entry point rather than a batch-processing tool.

7. **API deployment boundary**
   `api/app.py` exposes the detector as a **FastAPI** microservice.
   It accepts feature vectors over REST, loads the model artifact, and returns prediction metadata. This makes the IDS consumable by external systems such as a ground-control station, dashboard, or another orchestration service.

8. **Auxiliary intelligence and defense modules**
   The `modules/` directory contains specialized subsystems that extend the core detector:
   `xai_engine.py` for explainability, `zero_day_detector.py` for anomaly detection, `adversarial_engine.py` for FGSM-style hardening, `falcon_intelligence.py` and `tactical_briefing.py` for decision summarization, and `kinetic_response.py` / `ids_engine.py` for mitigation-oriented orchestration.
   These are best treated as **decision-support and defense layers** around the core classifier, not the core data path itself.

9. **Simulation and coordination layers**
   Several modules model higher-level defense concepts rather than direct packet processing: `rf_phy_layer.py`, `swarm_consensus.py`, `federated_swarm.py`, `temporal_memory.py`, `apex_engine.py`, and `vlm_verifier.py`.
   The README frames these as tactical or research extensions, so in an architecture diagram they belong in a separate optional layer above the detector, representing simulated physical-layer correlation, distributed alert consensus, or agent-style reasoning.

10. **Configuration and shared assets**
   `config/config.py` centralizes settings, while `models/` stores serialized artifacts and `results/` plus `RESULTS.md` capture benchmark/stress-test outputs.
   This creates a clear separation between **code**, **configuration**, **trained artifacts**, and **evaluation evidence**.

11. **Validation and reproducibility tooling**
   The `scripts/` folder contains end-to-end and phase checks (`full_system_test.py`, `verify_phase1.py`, `verify_phase2.py`, `generate_demo_data.py`), indicating the repo is designed to validate the whole pipeline rather than only train a model.
   These scripts are the integration layer that exercises data prep, inference, and system behavior under mixed traffic.

12. **Key architectural summary**
   If you draw the diagram, the most important boundaries are:
   **data ingestion/training** on one side, **real-time inference/API** in the middle, and **optional defense/explainability/coordination modules** on the other.
   The main dependencies are from raw traffic or dataset files into flow features, then into a trained XGBoost model, with FastAPI and live sniffer acting as the two operational front ends.

Main entry points: [`inference_engine.py`](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/inference_engine.py) (Inference engine), [`data_pipeline.py`](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/data_pipeline.py) (Data pipeline), [`models/model.pkl`](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/models/model.pkl) (Model artifacts), [`README.md`](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/README.md) (A-DIDS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_offline["Offline pipeline"]
  node_node_data_loader["Data loader<br/>dataset adapter<br/>[data_loader.py]"]
  node_node_pcap_processor["PCAP processor<br/>flow builder<br/>[pcap_processor.py]"]
  node_node_data_pipeline["Data pipeline<br/>feature pipeline<br/>[data_pipeline.py]"]
  node_node_train["Train model<br/>binary classifier training<br/>[train_model.py]"]
  node_node_train_multi["Multiclass train"]
  node_node_benchmark["Benchmarking<br/>evaluation"]
  node_node_harden["Hardening<br/>adversarial training<br/>[harden_model.py]"]
end

subgraph group_group_online["Online detection"]
  node_node_infer["Inference engine<br/>scoring layer"]
  node_node_sniffer["Live sniffer<br/>packet capture<br/>[live_sniffer.py]"]
  node_node_api["FastAPI app<br/>[app.py]"]
end

subgraph group_group_intel["Defense layers"]
  node_node_xai["Explainability<br/>xai<br/>[xai_engine.py]"]
  node_node_zero_day["Zero-day detect<br/>anomaly detection"]
  node_node_adv["Adversarial defense<br/>robustness"]
  node_node_ids["IDS orchestration<br/>coordination<br/>[ids_engine.py]"]
  node_node_response["Kinetic response<br/>mitigation"]
  node_node_swarm["Swarm consensus<br/>distributed alerting<br/>[swarm_consensus.py]"]
  node_node_falcon["Falcon intel<br/>decision support"]
  node_node_brief["Tactical briefing"]
end

subgraph group_group_ops["Ops and assets"]
  node_node_readme["A-DIDS<br/>repo overview<br/>[README.md]"]
  node_node_config["Config<br/>settings<br/>[config.py]"]
  node_node_models[("Model artifacts<br/>serialized models<br/>[model.pkl]")]
  node_node_verify["Validation scripts<br/>integration checks"]
end

node_node_readme -->|"defines pipeline"| node_node_data_pipeline
node_node_readme -->|"centers on"| node_node_infer
node_node_readme -->|"exposes via"| node_node_api
node_node_data_loader -->|"feeds"| node_node_pcap_processor
node_node_pcap_processor -->|"reconstructs flows"| node_node_data_pipeline
node_node_data_pipeline -->|"produces features for"| node_node_train
node_node_data_pipeline -->|"produces features for"| node_node_train_multi
node_node_train -->|"writes"| node_node_models
node_node_train_multi -->|"writes"| node_node_models
node_node_harden -->|"writes"| node_node_models
node_node_benchmark -->|"evaluates"| node_node_models
node_node_models -->|"loads"| node_node_infer
node_node_sniffer -->|"streams to"| node_node_infer
node_node_api -->|"calls"| node_node_infer
node_node_infer -.->|"explains with"| node_node_xai
node_node_infer -.->|"augments with"| node_node_zero_day
node_node_adv -.->|"supports"| node_node_harden
node_node_ids -->|"triggers"| node_node_response
node_node_swarm -.->|"feeds consensus"| node_node_ids
node_node_falcon -->|"summarizes into"| node_node_brief
node_node_verify -.->|"tests"| node_node_data_pipeline
node_node_verify -.->|"tests"| node_node_infer
node_node_config -->|"configures"| node_node_data_pipeline
node_node_config -->|"configures"| node_node_api

click node_node_readme "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/README.md"
click node_node_config "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/config/config.py"
click node_node_data_loader "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/data_loader.py"
click node_node_pcap_processor "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/pcap_processor.py"
click node_node_data_pipeline "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/data_pipeline.py"
click node_node_train "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/train_model.py"
click node_node_train_multi "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/train_multiclass.py"
click node_node_benchmark "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/benchmark_models.py"
click node_node_harden "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/harden_model.py"
click node_node_infer "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/inference_engine.py"
click node_node_sniffer "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/live_sniffer.py"
click node_node_api "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/api/app.py"
click node_node_models "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/models/model.pkl"
click node_node_xai "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/xai_engine.py"
click node_node_zero_day "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/zero_day_detector.py"
click node_node_adv "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/adversarial_engine.py"
click node_node_ids "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/ids_engine.py"
click node_node_response "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/kinetic_response.py"
click node_node_swarm "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/swarm_consensus.py"
click node_node_falcon "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/falcon_intelligence.py"
click node_node_brief "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/tactical_briefing.py"
click node_node_verify "https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/scripts/full_system_test.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_node_data_loader,node_node_pcap_processor,node_node_data_pipeline,node_node_train,node_node_train_multi,node_node_benchmark,node_node_harden toneBlue
class node_node_infer,node_node_sniffer,node_node_api toneAmber
class node_node_xai,node_node_zero_day,node_node_adv,node_node_ids,node_node_response,node_node_swarm,node_node_falcon,node_node_brief toneMint
class node_node_readme,node_node_config,node_node_models,node_node_verify toneRose
```

## Components

### Offline pipeline

Dataset ingestion, flow reconstruction, feature generation, and model training.

- [Data loader](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/data_loader.py): dataset adapter · Loads and normalizes raw dataset inputs for downstream processing. · `modules/data_loader.py`
- [PCAP processor](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/pcap_processor.py): flow builder · Reconstructs packets into bidirectional flows from capture files. · `pcap_processor.py`
- [Data pipeline](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/data_pipeline.py): feature pipeline · Converts captures and CSV data into model-ready flow features. · `data_pipeline.py`
- [Train model](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/train_model.py): binary classifier training · Trains the main detector model artifact. · `train_model.py`
- [Multiclass train](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/train_multiclass.py): multiclass training · Trains the multiclass detector variant. · `train_multiclass.py`
- [Benchmarking](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/benchmark_models.py): evaluation · Compares trained models and records performance results. · `benchmark_models.py`
- [Hardening](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/harden_model.py): adversarial training · Builds a hardened model variant for robustness. · `harden_model.py`

### Online detection

Real-time capture, inference, and API serving.

- [Inference engine](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/inference_engine.py): scoring layer · Turns feature vectors into predictions, confidence, and latency. · `inference_engine.py`
- [Live sniffer](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/live_sniffer.py): packet capture · Captures live traffic, assembles flows, and forwards them for scoring. · `live_sniffer.py`
- [FastAPI app](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/api/app.py): service · REST API for submitting features and returning predictions. · `api/app.py`

### Defense layers

Explainability, anomaly detection, mitigation, and coordination extensions.

- [Explainability](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/xai_engine.py): xai · Explains model decisions for operators and analysts. · `modules/xai_engine.py`
- [Zero-day detect](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/zero_day_detector.py): anomaly detection · Adds novelty or anomaly-based detection around the classifier. · `modules/zero_day_detector.py`
- [Adversarial defense](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/adversarial_engine.py): robustness · Supports FGSM-style hardening and robustness checks. · `modules/adversarial_engine.py`
- [IDS orchestration](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/ids_engine.py): coordination · Coordinates detection and mitigation-oriented subsystems. · `modules/ids_engine.py`
- [Kinetic response](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/kinetic_response.py): mitigation · Represents response actions after detection or escalation. · `modules/kinetic_response.py`
- [Swarm consensus](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/swarm_consensus.py): distributed alerting · Models distributed alert agreement across agents or nodes. · `modules/swarm_consensus.py`
- [Falcon intel](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/falcon_intelligence.py): decision support · Summarizes findings into operator-friendly intelligence. · `modules/falcon_intelligence.py`
- [Tactical briefing](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/modules/tactical_briefing.py): briefing · Formats detection outputs into actionable briefings. · `modules/tactical_briefing.py`

### Ops and assets

Configuration, artifacts, and validation tooling.

- [A-DIDS](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/README.md): repo overview · Drone-network intrusion detection system organized around a flow-based ML pipeline. · `README.md`
- [Config](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/config/config.py): settings · Central configuration for runtime and pipeline behavior. · `config/config.py`
- [Model artifacts](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/models/model.pkl): serialized models · Persisted detector artifacts used by inference and deployment. · `models/model.pkl`
- [Validation scripts](https://github.com/shemayon/adids-advanced-drone-intrusion-detection-system-2026/blob/main/scripts/full_system_test.py): integration checks · End-to-end and phase checks that exercise the full system. · `scripts/full_system_test.py`

## Connections

- A-DIDS → Data pipeline: defines pipeline · Documents the offline flow from dataset to features.
- A-DIDS → Inference engine: centers on · Describes inference as the main scoring boundary.
- A-DIDS → FastAPI app: exposes via · Surfaces detection as a service.
- Data loader → PCAP processor: feeds · Loads raw dataset inputs for packet/flow processing.
- PCAP processor → Data pipeline: reconstructs flows · Transforms captures into bidirectional flow records.
- Data pipeline → Train model: produces features for · Generates model-ready vectors used in training.
- Data pipeline → Multiclass train: produces features for · Supports the multiclass training path.
- Train model → Model artifacts: writes · Persists the main trained model artifact.
- Multiclass train → Model artifacts: writes · Persists the multiclass model artifact.
- Hardening → Model artifacts: writes · Produces a hardened model artifact.
- Benchmarking → Model artifacts: evaluates · Compares stored model variants.
- Model artifacts → Inference engine: loads · Provides the serialized model used for scoring.
- Live sniffer → Inference engine: streams to · Sends reconstructed live flows for immediate scoring.
- FastAPI app → Inference engine: calls · Uses the inference layer to generate predictions.
- Inference engine → Explainability: explains with · Can pair predictions with explanations.
- Inference engine → Zero-day detect: augments with · Can be combined with anomaly detection.
- Adversarial defense → Hardening: supports · Provides robustness-oriented hardening logic.
- IDS orchestration → Kinetic response: triggers · Coordinates mitigation after detection.
- Swarm consensus → IDS orchestration: feeds consensus · Contributes distributed agreement signals.
- Falcon intel → Tactical briefing: summarizes into · Turns detector output into operator briefings.
- Validation scripts → Data pipeline: tests · Exercises dataset and feature preparation.
- Validation scripts → Inference engine: tests · Validates scoring behavior under mixed traffic.
- Config → Data pipeline: configures · Supplies shared runtime and pipeline settings.
- Config → FastAPI app: configures · Supplies API/runtime settings.
