# rohith-sp/netguard-ai architecture

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

- Interactive diagram: https://gitdiagram.com/rohith-sp/netguard-ai
- Repository: https://github.com/rohith-sp/netguard-ai

## Overview

1. **Overall shape**
   NetGuard AI is a three-tier IoT security system: edge nodes publish telemetry over MQTT, a Python backend performs real-time classification and chat-style analysis, and a Next.js dashboard visualizes live security state. The repository also includes the offline ML data pipeline and ESP32 firmware/simulations used to generate the telemetry.

2. **Primary data flow**
   The core path is: **ESP32 node or Python simulator → MQTT broker (`broker.hivemq.com`) → FastAPI backend (`dashboard/backend/main.py`) → WebSocket stream → Next.js UI**. The backend is the central integration point, translating broker traffic into browser-friendly live updates and security events.

3. **Edge / device layer**
   Under `hardware-simulation/` are three PlatformIO ESP32 firmwares:
   - `NetGuard_DHT_Node` for environmental telemetry,
   - `NetGuard_LDR_Node` for light telemetry,
   - `NetGuard_Attacker_Node` for malicious or anomalous traffic behavior.
   
   These represent the source devices that publish to MQTT topics like `netguard/#`. They define the device-side boundary of the system.

4. **Local simulation fallback**
   `dashboard/backend/node_simulator.py` is a Python stand-in for the ESP32 network during local demos. It publishes realistic telemetry in concurrent threads and reacts to dashboard commands. This exists because the README notes Wokwi virtual WiFi cannot reliably publish outbound MQTT to the public broker.

5. **Backend orchestration**
   `dashboard/backend/main.py` is the operational hub. Its responsibilities are to:
   - subscribe to MQTT telemetry,
   - maintain the live device state,
   - run periodic ML inference every 5 seconds,
   - emit results to the frontend via WebSockets,
   - publish time sync messages on `netguard/timesync`,
   - expose control paths for node actions initiated from the dashboard.

6. **ML inference boundary**
   The backend consumes a trained Random Forest model from the `mqtt_collector` pipeline and uses it for classification into states such as `NORMAL`, `DOS_FLOOD`, `REPLAY_ATTACK`, and `SLOW_RATE_ATTACK`. SHAP explainability is computed alongside predictions so the UI can show feature-level drivers of each alert.

7. **RAG / analyst assistant**
   `dashboard/backend/rag.py` provides the natural-language analysis layer. It combines live telemetry context, model/SHAP outputs, and documentation from `mqtt_collector/DATASETS.md`, then routes queries through Groq or Gemini with fallback expert logic. Architecturally, this is a sidecar intelligence service attached to the backend rather than part of the core detection pipeline.

8. **Frontend SOC dashboard**
   `dashboard/frontend/` is a Next.js application that renders the operator console. The main page composes:
   - `TopologyTab.tsx` for the live device graph,
   - `Graphs.tsx` for temporal threat curves,
   - `Panels.tsx` for status, SHAP, and control views.
   
   `useLiveData.ts` is the client-side bridge to backend WebSockets, keeping the UI synchronized with backend events.

9. **Telemetry collection and model training**
   `mqtt_collector/` is the offline analytics pipeline:
   - `collector.py` captures raw MQTT traffic into logs/CSVs,
   - `feature_extractor.py` turns raw telemetry into sliding-window features,
   - `trainer.py` produces the Random Forest model artifact.
   
   This pipeline is separate from the live backend and defines the training-to-inference boundary.

10. **Artifacts and datasets**
   The collector folder contains the model inputs/outputs, including `dataset/raw_telemetry.log`, `dataset/features.csv`, and `dataset/netguard_dataset.csv`, plus `netguard_model.pkl` referenced by the runtime system. `DATASETS.md` documents the meaning of the features used both for training and for dashboard explanations.

11. **Prototype / demo surface**
   `Phase 1 Simulation/` and the root HTML files are standalone simulation/demo assets, likely preserved as early-stage or presentation-only views. They are not part of the runtime path, but they show the project evolved from static simulation into the live MQTT + backend + dashboard architecture.

12. **Important external dependencies**
   The architecture depends on a public MQTT broker (`broker.hivemq.com:1883`) as the message bus, and on external LLM APIs for the RAG assistant. These external services materially affect system behavior: broker availability affects telemetry flow, while Groq/Gemini availability affects analyst chat responses.

13. **Architectural boundary summary**
   The cleanest diagram is:
   - **Edge layer**: ESP32 nodes / Python simulator
   - **Messaging layer**: MQTT broker
   - **Detection layer**: FastAPI backend with ML + SHAP + RAG
   - **Presentation layer**: Next.js SOC dashboard
   - **Offline pipeline**: MQTT capture → feature extraction → model training
   
   That separation captures the repo’s main runtime path and the supporting analytics workflow.

Main entry points: [`dashboard/backend/main.py`](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/main.py) (Backend core), [`dashboard/frontend/app/page.tsx`](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/page.tsx) (SOC dashboard), [`dashboard/backend/rag.py`](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/rag.py) (RAG assistant), [`mqtt_collector/collector.py`](https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/collector.py) (Collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge layer"]
  node_dht_node["DHT node<br/>ESP32 firmware<br/>[main.cpp]"]
  node_ldr_node["LDR node<br/>ESP32 firmware<br/>[main.cpp]"]
  node_attacker_node["Attacker node<br/>ESP32 firmware<br/>[main.cpp]"]
end

subgraph group_backend["Detection layer"]
  node_node_sim["Node simulator<br/>Python simulator<br/>[node_simulator.py]"]
  node_mqtt_broker[("MQTT broker<br/>external bus")]
  node_backend_main["Backend core<br/>FastAPI service<br/>[main.py]"]
  node_ml_model["RF model<br/>inference artifact"]
  node_shap_logic["SHAP explainers<br/>explainability<br/>[main.py]"]
  node_rag_assistant["RAG assistant<br/>nl analysis<br/>[rag.py]"]
  node_llm_apis[("LLM APIs<br/>external ai")]
end

subgraph group_frontend["Presentation layer"]
  node_frontend_app["SOC dashboard<br/>Next.js app<br/>[page.tsx]"]
  node_live_hook["Live hook<br/>websocket client<br/>[useLiveData.ts]"]
  node_topology_ui["Topology view<br/>ui panel<br/>[TopologyTab.tsx]"]
  node_graphs_ui["Threat graphs<br/>ui panel<br/>[Graphs.tsx]"]
  node_panels_ui["Control panels<br/>ui panel<br/>[Panels.tsx]"]
end

subgraph group_offline["Offline pipeline"]
  node_collector["Collector<br/>mqtt capture<br/>[collector.py]"]
  node_features["Feature extractor<br/>ml prep"]
  node_trainer["Trainer<br/>ml training<br/>[trainer.py]"]
  node_datasets_md["Dataset guide<br/>documentation<br/>[DATASETS.md]"]
end

subgraph group_legacy["Prototype surface"]
  node_phase1_demo["Phase 1 demo<br/>legacy html<br/>[index.html]"]
end

node_dht_node -->|"publish telemetry"| node_mqtt_broker
node_ldr_node -->|"publish telemetry"| node_mqtt_broker
node_attacker_node -->|"publish attacks"| node_mqtt_broker
node_node_sim -->|"publish fallback"| node_mqtt_broker
node_mqtt_broker -->|"subscribe"| node_backend_main
node_backend_main -->|"timesync/control"| node_mqtt_broker
node_backend_main -->|"load model"| node_ml_model
node_backend_main -->|"explain predictions"| node_shap_logic
node_backend_main -->|"chat analysis"| node_rag_assistant
node_rag_assistant -->|"grounding"| node_datasets_md
node_rag_assistant -->|"query LLM"| node_llm_apis
node_backend_main -->|"websocket stream"| node_live_hook
node_live_hook -->|"receive events"| node_backend_main
node_frontend_app -->|"compose"| node_topology_ui
node_frontend_app -->|"compose"| node_graphs_ui
node_frontend_app -->|"compose"| node_panels_ui
node_collector -->|"build dataset"| node_features
node_features -->|"train model"| node_trainer
node_collector -->|"document"| node_datasets_md
node_trainer -->|"export artifact"| node_ml_model
node_phase1_demo -.->|"precedes"| node_frontend_app

click node_dht_node "https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_DHT_Node/src/main.cpp"
click node_ldr_node "https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_LDR_Node/src/main.cpp"
click node_attacker_node "https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_Attacker_Node/src/main.cpp"
click node_node_sim "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/node_simulator.py"
click node_backend_main "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/main.py"
click node_shap_logic "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/main.py"
click node_rag_assistant "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/rag.py"
click node_frontend_app "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/page.tsx"
click node_live_hook "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/hooks/useLiveData.ts"
click node_topology_ui "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/TopologyTab.tsx"
click node_graphs_ui "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/Graphs.tsx"
click node_panels_ui "https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/Panels.tsx"
click node_collector "https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/collector.py"
click node_features "https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/feature_extractor.py"
click node_trainer "https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/trainer.py"
click node_datasets_md "https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/DATASETS.md"
click node_phase1_demo "https://github.com/rohith-sp/netguard-ai/blob/main/Phase 1 Simulation/index.html"

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_dht_node,node_ldr_node,node_attacker_node toneBlue
class node_node_sim,node_mqtt_broker,node_backend_main,node_ml_model,node_shap_logic,node_rag_assistant,node_llm_apis toneAmber
class node_frontend_app,node_live_hook,node_topology_ui,node_graphs_ui,node_panels_ui toneMint
class node_collector,node_features,node_trainer,node_datasets_md toneRose
class node_phase1_demo toneIndigo
```

## Components

### Edge layer

ESP32 telemetry sources and local simulation

- [DHT node](https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_DHT_Node/src/main.cpp): ESP32 firmware · Publishes environmental telemetry from the DHT device · `hardware-simulation/NetGuard_DHT_Node/src/main.cpp`
- [LDR node](https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_LDR_Node/src/main.cpp): ESP32 firmware · Publishes light-sensor telemetry to MQTT topics · `hardware-simulation/NetGuard_LDR_Node/src/main.cpp`
- [Attacker node](https://github.com/rohith-sp/netguard-ai/blob/main/hardware-simulation/NetGuard_Attacker_Node/src/main.cpp): ESP32 firmware · Generates anomalous or malicious-looking traffic patterns · `hardware-simulation/NetGuard_Attacker_Node/src/main.cpp`

### Detection layer

FastAPI runtime that ingests MQTT, classifies events, and serves analysis

- [Node simulator](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/node_simulator.py): Python simulator · Local stand-in that publishes telemetry when hardware publishing is unavailable · `dashboard/backend/node_simulator.py`
- **MQTT broker**: external bus · Public message bus used for telemetry and control topics
- [Backend core](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/main.py): FastAPI service · Subscribes to MQTT, tracks live state, runs inference, emits WebSocket updates, and handles control flow · `dashboard/backend/main.py`
- **RF model**: inference artifact · Trained classifier used to label live traffic states such as normal and attack modes
- [SHAP explainers](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/main.py): explainability · Computes feature-level drivers for predictions shown in the dashboard · `dashboard/backend/main.py`
- [RAG assistant](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/backend/rag.py): nl analysis · Natural-language analyst layer combining live context, docs, and fallback logic · `dashboard/backend/rag.py`
- **LLM APIs**: external ai · Groq or Gemini backends used for chat-style analysis responses

### Presentation layer

Next.js SOC dashboard and live UI

- [SOC dashboard](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/page.tsx): Next.js app · Operator console that renders live topology, trends, status, SHAP, and controls · `dashboard/frontend/app/page.tsx`
- [Live hook](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/hooks/useLiveData.ts): websocket client · Client-side bridge that keeps the UI synchronized with backend events · `dashboard/frontend/app/hooks/useLiveData.ts`
- [Topology view](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/TopologyTab.tsx): ui panel · Renders the live device graph and node relationships · `dashboard/frontend/app/components/TopologyTab.tsx`
- [Threat graphs](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/Graphs.tsx): ui panel · Shows temporal threat and telemetry curves · `dashboard/frontend/app/components/Graphs.tsx`
- [Control panels](https://github.com/rohith-sp/netguard-ai/blob/main/dashboard/frontend/app/components/Panels.tsx): ui panel · Shows status, SHAP output, and operator control views · `dashboard/frontend/app/components/Panels.tsx`

### Offline pipeline

MQTT capture, feature engineering, and model training

- [Collector](https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/collector.py): mqtt capture · Records raw MQTT telemetry into logs and CSV datasets · `mqtt_collector/collector.py`
- [Feature extractor](https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/feature_extractor.py): ml prep · Transforms telemetry into sliding-window features for training · `mqtt_collector/feature_extractor.py`
- [Trainer](https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/trainer.py): ml training · Produces the Random Forest model artifact from collected data · `mqtt_collector/trainer.py`
- [Dataset guide](https://github.com/rohith-sp/netguard-ai/blob/main/mqtt_collector/DATASETS.md): documentation · Documents feature meanings and dataset structure used by training and analysis · `mqtt_collector/DATASETS.md`

### Prototype surface

Standalone demo assets kept outside the main runtime path

- [Phase 1 demo](https://github.com/rohith-sp/netguard-ai/blob/HEAD/Phase%201%20Simulation/index.html): legacy html · Standalone simulation and presentation assets kept outside the main runtime · `Phase 1 Simulation/index.html`

## Connections

- DHT node → MQTT broker: publish telemetry · Sensor telemetry is sent to MQTT topics
- LDR node → MQTT broker: publish telemetry · Sensor telemetry is sent to MQTT topics
- Attacker node → MQTT broker: publish attacks · Malicious or anomalous patterns are emitted as MQTT traffic
- Node simulator → MQTT broker: publish fallback · Local simulator replaces hardware during demos
- MQTT broker → Backend core: subscribe · Backend ingests live MQTT traffic and control signals
- Backend core → MQTT broker: timesync/control · Backend publishes time sync and node action messages
- Backend core → RF model: load model · Inference service uses the trained classifier artifact
- Backend core → SHAP explainers: explain predictions · Backend computes feature contributions alongside classification
- Backend core → RAG assistant: chat analysis · Backend routes analyst questions and context to the RAG layer
- RAG assistant → Dataset guide: grounding · Assistant uses dataset documentation as reference context
- RAG assistant → LLM APIs: query LLM · Fallback responses are generated through external model APIs
- Backend core → Live hook: websocket stream · Live updates are pushed to the browser client
- Live hook → Backend core: receive events · Client subscribes to backend live data
- SOC dashboard → Topology view: compose · Main dashboard assembles the topology view
- SOC dashboard → Threat graphs: compose · Main dashboard assembles temporal visualizations
- SOC dashboard → Control panels: compose · Main dashboard assembles status and control panels
- Collector → Feature extractor: build dataset · Raw telemetry is converted into feature tables
- Feature extractor → Trainer: train model · Engineered features feed model training
- Collector → Dataset guide: document · Captured telemetry schema is described for downstream use
- Trainer → RF model: export artifact · Training produces the model used by the runtime backend
- Phase 1 demo → SOC dashboard: precedes · Early static demo surface evolved into the live dashboard
