# nadjiho12/packet-iq-ai architecture

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

- Interactive diagram: https://gitdiagram.com/nadjiho12/packet-iq-ai
- Repository: https://github.com/nadjiho12/packet-iq-ai

## Overview

PacketIQ AI is a packet-capture threat analysis product, exposed both as a CLI and a web dashboard. The main workflow accepts a PCAP, parses packets, aggregates flows, detects rule-based alerts, optionally enriches them with AI and email, and presents or stores the results. The web application also supports alert investigation/export, metrics, data reset, and AI-key settings. Backend service wiring and some endpoints are only partially excerpted, so uncertain links are omitted or marked unverified.

Main entry points: [`backend/app/pipeline.py`](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/pipeline.py) (CLI Pipeline), [`backend/app/service.py`](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/service.py) (Upload Service), [`frontend/src/pages/Dashboard.jsx`](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/pages/Dashboard.jsx) (Dashboard), [`backend/app/main.py`](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/main.py) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Packet Ingestion"]
  node_capture["Capture And Parse<br/>[capture.py]"]
end

subgraph group_analysis["Threat Analysis"]
  node_flows["Flow Aggregation<br/>[flow_engine.py]"]
  node_detection["Detection Rules<br/>[detection.py]"]
  node_pipeline["CLI Pipeline<br/>[pipeline.py]"]
  node_service["Upload Service<br/>[service.py]"]
end

subgraph group_web["Web Application"]
  node_webui["Dashboard<br/>[Dashboard.jsx]"]
  node_uploadui["Upload Panel<br/>[UploadPanel.jsx]"]
  node_alertui["Alert List<br/>[AlertList.jsx]"]
  node_keyui["API Key Dialog<br/>[ApiKeyDialog.jsx]"]
  node_api["Frontend API<br/>[api.js]"]
  node_apiapp["HTTP API<br/>[main.py]"]
end

subgraph group_state["Persistence And Settings"]
  node_database["Database Setup<br/>[database.py]"]
  node_models["Upload And Alert Models<br/>[models.py]"]
  node_store[("Results Database")]
  node_config["Application Config<br/>[config.py]"]
  node_settings["AI Settings Store<br/>[settings_store.py]"]
end

subgraph group_notify["Enrichment And Notification"]
  node_ai["AI Investigation<br/>[ai_agent.py]"]
  node_notifier["Email Notifier<br/>[notifier.py]"]
end

node_analyst(("Analyst"))
node_provider{{"AI Provider"}}
node_smtp{{"SMTP Server"}}

node_analyst -->|"uses"| node_webui
node_webui -->|"renders"| node_uploadui
node_webui -->|"renders"| node_alertui
node_webui -->|"renders"| node_keyui
node_webui -->|"requests data"| node_api
node_uploadui -->|"uploads capture"| node_api
node_alertui -->|"investigates and exports"| node_api
node_keyui -->|"manages key settings"| node_api
node_api -->|"calls HTTP endpoints"| node_apiapp
node_analyst -->|"runs CLI"| node_pipeline
node_pipeline -->|"reads PCAP"| node_capture
node_pipeline -->|"runs detection"| node_detection
node_detection -->|"uses flow aggregation"| node_flows
node_apiapp -.->|"processes uploads"| node_service
node_service -.->|"parses PCAP"| node_capture
node_service -.->|"detects threats"| node_detection
node_service -.->|"investigates alerts"| node_ai
node_service -.->|"sends notifications"| node_notifier
node_pipeline -->|"investigates alerts"| node_ai
node_pipeline -->|"sends email"| node_notifier
node_ai -->|"requests report"| node_provider
node_notifier -->|"sends email"| node_smtp
node_apiapp -->|"uses sessions"| node_database
node_database -->|"registers tables"| node_models
node_database -->|"loads database URL"| node_config
node_models -->|"persists derived results"| node_store
node_apiapp -->|"reads and updates"| node_settings
node_apiapp -->|"queries and stores results"| node_store

click node_capture "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/capture.py"
click node_flows "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/flow_engine.py"
click node_detection "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/detection.py"
click node_pipeline "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/pipeline.py"
click node_webui "https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/pages/Dashboard.jsx"
click node_uploadui "https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/UploadPanel.jsx"
click node_alertui "https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/AlertList.jsx"
click node_keyui "https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/ApiKeyDialog.jsx"
click node_api "https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/api.js"
click node_apiapp "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/main.py"
click node_service "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/service.py"
click node_ai "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/ai_agent.py"
click node_notifier "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/notifier.py"
click node_database "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/database.py"
click node_models "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/models.py"
click node_config "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/config.py"
click node_settings "https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/settings_store.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_capture toneBlue
class node_flows,node_detection,node_pipeline,node_service toneAmber
class node_webui,node_uploadui,node_alertui,node_keyui,node_api,node_apiapp,node_smtp toneMint
class node_database,node_models,node_store,node_config,node_settings toneRose
class node_ai,node_notifier,node_analyst,node_provider toneIndigo
```

## Components

### Packet Ingestion

- [Capture And Parse](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/capture.py): `backend/app/capture.py`

### Threat Analysis

- [Flow Aggregation](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/flow_engine.py): `backend/app/flow_engine.py`
- [Detection Rules](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/detection.py): `backend/app/detection.py`
- [CLI Pipeline](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/pipeline.py): `backend/app/pipeline.py`
- [Upload Service](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/service.py): `backend/app/service.py`

### Web Application

- [Dashboard](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Upload Panel](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/UploadPanel.jsx): `frontend/src/components/UploadPanel.jsx`
- [Alert List](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/AlertList.jsx): `frontend/src/components/AlertList.jsx`
- [API Key Dialog](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/components/ApiKeyDialog.jsx): `frontend/src/components/ApiKeyDialog.jsx`
- [Frontend API](https://github.com/nadjiho12/packet-iq-ai/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [HTTP API](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/main.py): `backend/app/main.py`

### Persistence And Settings

- [Database Setup](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/database.py): `backend/app/database.py`
- [Upload And Alert Models](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/models.py): `backend/app/models.py`
- **Results Database**
- [Application Config](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/config.py): `backend/app/config.py`
- [AI Settings Store](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/settings_store.py): `backend/app/settings_store.py`

### Enrichment And Notification

- [AI Investigation](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/ai_agent.py): `backend/app/ai_agent.py`
- [Email Notifier](https://github.com/nadjiho12/packet-iq-ai/blob/main/backend/app/notifier.py): `backend/app/notifier.py`

### Other components

- **Analyst**
- **AI Provider**
- **SMTP Server**

## Connections

- Analyst → Dashboard: uses
- Dashboard → Upload Panel: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Alert List: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → API Key Dialog: renders (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Frontend API: requests data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Upload Panel → Frontend API: uploads capture (evidence: `frontend/src/components/UploadPanel.jsx`)
- Alert List → Frontend API: investigates and exports (evidence: `frontend/src/components/AlertList.jsx`)
- API Key Dialog → Frontend API: manages key settings (evidence: `frontend/src/components/ApiKeyDialog.jsx`)
- Frontend API → HTTP API: calls HTTP endpoints (evidence: `frontend/src/api.js`)
- Analyst → CLI Pipeline: runs CLI (evidence: `README.md`)
- CLI Pipeline → Capture And Parse: reads PCAP (evidence: `backend/app/pipeline.py`)
- CLI Pipeline → Detection Rules: runs detection (evidence: `backend/app/pipeline.py`)
- Detection Rules → Flow Aggregation: uses flow aggregation (evidence: `backend/app/detection.py`)
- HTTP API → Upload Service: processes uploads (evidence: `backend/app/main.py`)
- Upload Service → Capture And Parse: parses PCAP (evidence: `backend/app/service.py`)
- Upload Service → Detection Rules: detects threats (evidence: `backend/app/service.py`)
- Upload Service → AI Investigation: investigates alerts (evidence: `backend/app/service.py`)
- Upload Service → Email Notifier: sends notifications
- CLI Pipeline → AI Investigation: investigates alerts (evidence: `backend/app/pipeline.py`)
- CLI Pipeline → Email Notifier: sends email (evidence: `backend/app/pipeline.py`)
- AI Investigation → AI Provider: requests report (evidence: `README.md`)
- Email Notifier → SMTP Server: sends email (evidence: `README.md`)
- HTTP API → Database Setup: uses sessions (evidence: `backend/app/main.py`)
- Database Setup → Upload And Alert Models: registers tables (evidence: `backend/app/database.py`)
- Database Setup → Application Config: loads database URL (evidence: `backend/app/database.py`)
- Upload And Alert Models → Results Database: persists derived results (evidence: `backend/app/models.py`)
- HTTP API → AI Settings Store: reads and updates (evidence: `backend/app/main.py`)
- HTTP API → Results Database: queries and stores results (evidence: `backend/app/main.py`)
