# yagohehe/iotgpt architecture

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

- Interactive diagram: https://gitdiagram.com/yagohehe/iotgpt
- Repository: https://github.com/yagohehe/iotgpt

## Overview

IoTGPT combines a background MQTT intrusion-detection pipeline with an operator-facing LLM agent. Simulated traffic is stored and classified in two stages; the agent then answers operator queries using predictions, event history, and RAG documentation, and can submit mitigation plans for human review. The graph preserves the documented evaluation capability but omits experiment runners and training/deployment machinery. Edges for the classifier pipeline and some integrations follow README statements; unsampled implementation details are not inferred.

Main entry points: [`app/tools.py`](https://github.com/yagohehe/iotgpt/blob/main/app/tools.py) (Agent tools), [`app/agent.py`](https://github.com/yagohehe/iotgpt/blob/main/app/agent.py) (ReAct agent), [`classifier/ml_models_classification.py`](https://github.com/yagohehe/iotgpt/blob/main/classifier/ml_models_classification.py) (Binary detection), [`app/static/dashboard.html`](https://github.com/yagohehe/iotgpt/blob/main/app/static/dashboard.html) (Web dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_traffic["Traffic and IDS"]
  node_simulator["MQTT simulator"]
  node_events[("Event store")]
  node_binary["Binary detection"]
  node_attacktype["Attack classification"]
  node_predictions[("Prediction store")]
end

subgraph group_agent["Agent and RAG"]
  node_agent["ReAct agent<br/>[agent.py]"]
  node_prompts["System prompts"]
  node_tools["Agent tools<br/>[tools.py]"]
  node_ragdocs["RAG knowledge"]
  node_vectorstore[("Chroma index")]
end

subgraph group_operator["Operator interface"]
  node_dashboard["Web dashboard<br/>[dashboard.html]"]
  node_api["FastAPI backend<br/>[server.py]"]
end

subgraph group_review["Human review"]
  node_hitl[("HITL requests")]
  node_hitlrouter["HITL API<br/>[hitl_routes.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation["Agent evaluation"]
end

node_operator(("Security operator"))

node_simulator -->|"inserts events"| node_events
node_events -->|"classifies events"| node_binary
node_binary -->|"classifies attacks"| node_attacktype
node_attacktype -->|"writes predictions"| node_predictions
node_operator -->|"uses"| node_dashboard
node_dashboard -->|"queries"| node_api
node_api -->|"invokes"| node_agent
node_agent -->|"loads"| node_prompts
node_agent -->|"invokes tools"| node_tools
node_tools -->|"queries"| node_predictions
node_tools -->|"queries"| node_events
node_tools -->|"retrieves context"| node_ragdocs
node_tools -->|"uses index"| node_vectorstore
node_tools -->|"creates request"| node_hitl
node_operator -->|"reviews plans"| node_hitlrouter
node_hitlrouter -->|"reads and updates"| node_hitl
node_evaluation -->|"evaluates"| node_agent

click node_simulator "https://github.com/yagohehe/iotgpt/blob/main/simulator/mqtt_log_simulator.py"
click node_binary "https://github.com/yagohehe/iotgpt/blob/main/classifier/ml_models_classification.py"
click node_attacktype "https://github.com/yagohehe/iotgpt/blob/main/classifier/ml_models_classification.py"
click node_dashboard "https://github.com/yagohehe/iotgpt/blob/main/app/static/dashboard.html"
click node_api "https://github.com/yagohehe/iotgpt/blob/main/app/server.py"
click node_agent "https://github.com/yagohehe/iotgpt/blob/main/app/agent.py"
click node_prompts "https://github.com/yagohehe/iotgpt/tree/main/app/prompt"
click node_tools "https://github.com/yagohehe/iotgpt/blob/main/app/tools.py"
click node_ragdocs "https://github.com/yagohehe/iotgpt/tree/main/app/rag_doc"
click node_vectorstore "https://github.com/yagohehe/iotgpt/tree/main/app/chroma_mqtt_qwen"
click node_hitlrouter "https://github.com/yagohehe/iotgpt/blob/main/app/hitl_routes.py"
click node_evaluation "https://github.com/yagohehe/iotgpt/blob/main/evaluation/runners/exp2b_agent_qualitative.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_simulator,node_events,node_binary,node_attacktype,node_predictions toneBlue
class node_agent,node_prompts,node_tools,node_ragdocs,node_vectorstore toneAmber
class node_dashboard,node_api toneMint
class node_hitl,node_hitlrouter toneRose
class node_evaluation,node_operator toneIndigo
```

## Components

### Traffic and IDS

- [MQTT simulator](https://github.com/yagohehe/iotgpt/blob/main/simulator/mqtt_log_simulator.py): `simulator/mqtt_log_simulator.py`
- **Event store**
- [Binary detection](https://github.com/yagohehe/iotgpt/blob/main/classifier/ml_models_classification.py): `classifier/ml_models_classification.py`
- [Attack classification](https://github.com/yagohehe/iotgpt/blob/main/classifier/ml_models_classification.py): `classifier/ml_models_classification.py`
- **Prediction store**

### Agent and RAG

- [ReAct agent](https://github.com/yagohehe/iotgpt/blob/main/app/agent.py): `app/agent.py`
- [System prompts](https://github.com/yagohehe/iotgpt/tree/main/app/prompt): `app/prompt`
- [Agent tools](https://github.com/yagohehe/iotgpt/blob/main/app/tools.py): `app/tools.py`
- [RAG knowledge](https://github.com/yagohehe/iotgpt/tree/main/app/rag_doc): `app/rag_doc`
- [Chroma index](https://github.com/yagohehe/iotgpt/tree/main/app/chroma_mqtt_qwen): `app/chroma_mqtt_qwen`

### Operator interface

- [Web dashboard](https://github.com/yagohehe/iotgpt/blob/main/app/static/dashboard.html): `app/static/dashboard.html`
- [FastAPI backend](https://github.com/yagohehe/iotgpt/blob/main/app/server.py): `app/server.py`

### Human review

- **HITL requests**
- [HITL API](https://github.com/yagohehe/iotgpt/blob/main/app/hitl_routes.py): `app/hitl_routes.py`

### Evaluation

- [Agent evaluation](https://github.com/yagohehe/iotgpt/blob/main/evaluation/runners/exp2b_agent_qualitative.py): `evaluation/runners/exp2b_agent_qualitative.py`

### Other components

- **Security operator**

## Connections

- MQTT simulator → Event store: inserts events (evidence: `README.md`)
- Event store → Binary detection: classifies events (evidence: `README.md`)
- Binary detection → Attack classification: classifies attacks (evidence: `README.md`)
- Attack classification → Prediction store: writes predictions (evidence: `README.md`)
- Security operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → FastAPI backend: queries (evidence: `app/server.py`)
- FastAPI backend → ReAct agent: invokes (evidence: `app/server.py`)
- ReAct agent → System prompts: loads (evidence: `app/agent.py`)
- ReAct agent → Agent tools: invokes tools (evidence: `app/agent.py`)
- Agent tools → Prediction store: queries (evidence: `README.md`)
- Agent tools → Event store: queries (evidence: `README.md`)
- Agent tools → RAG knowledge: retrieves context (evidence: `README.md`)
- Agent tools → Chroma index: uses index (evidence: `app/tools.py`)
- Agent tools → HITL requests: creates request (evidence: `README.md`)
- Security operator → HITL API: reviews plans (evidence: `README.md`)
- HITL API → HITL requests: reads and updates (evidence: `app/hitl_routes.py`)
- Agent evaluation → ReAct agent: evaluates (evidence: `evaluation/runners/exp2b_agent_qualitative.py`)