How rohith-sp/netguard-ai works
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: main.py Backend core · page.tsx SOC dashboard · rag.py RAG assistant · collector.py Collector
Components 20
Edge layer
ESP32 telemetry sources and local simulation
- DHT node · Publishes environmental telemetry from the DHT device
hardware-simulation/NetGuard_DHT_Node/src/main.cpp - LDR node · Publishes light-sensor telemetry to MQTT topics
hardware-simulation/NetGuard_LDR_Node/src/main.cpp - Attacker node · 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 · Local stand-in that publishes telemetry when hardware publishing is unavailable
dashboard/backend/node_simulator.py - MQTT broker · Public message bus used for telemetry and control topics
- Backend core · Subscribes to MQTT, tracks live state, runs inference, emits WebSocket updates, and handles control flow
dashboard/backend/main.py - RF model · Trained classifier used to label live traffic states such as normal and attack modes
- SHAP explainers · Computes feature-level drivers for predictions shown in the dashboard
dashboard/backend/main.py - RAG assistant · Natural-language analyst layer combining live context, docs, and fallback logic
dashboard/backend/rag.py - LLM APIs · Groq or Gemini backends used for chat-style analysis responses
Presentation layer
Next.js SOC dashboard and live UI
- SOC dashboard · Operator console that renders live topology, trends, status, SHAP, and controls
dashboard/frontend/app/page.tsx - Live hook · Client-side bridge that keeps the UI synchronized with backend events
dashboard/frontend/app/hooks/useLiveData.ts - Topology view · Renders the live device graph and node relationships
dashboard/frontend/app/components/TopologyTab.tsx - Threat graphs · Shows temporal threat and telemetry curves
dashboard/frontend/app/components/Graphs.tsx - Control panels · Shows status, SHAP output, and operator control views
dashboard/frontend/app/components/Panels.tsx
Offline pipeline
MQTT capture, feature engineering, and model training
- Collector · Records raw MQTT telemetry into logs and CSV datasets
mqtt_collector/collector.py - Feature extractor · Transforms telemetry into sliding-window features for training
mqtt_collector/feature_extractor.py - Trainer · Produces the Random Forest model artifact from collected data
mqtt_collector/trainer.py - Dataset guide · 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 · Standalone simulation and presentation assets kept outside the main runtime
Phase 1 Simulation/index.html
Connections 21
- 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