# jadkissa/mpu-project02 architecture

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

- Interactive diagram: https://gitdiagram.com/jadkissa/mpu-project02
- Repository: https://github.com/jadkissa/mpu-project02

## Overview

M-NIDS combines signature detection with two behavioral stages: per-flow anomaly scoring and windowed source-IP scan/persistence analysis. Both alert streams are normalized by the watcher, ingested by FastAPI, and stored for dashboard queries; PostgreSQL also supports push alerting to Telegram through n8n. Users view refreshed alert tables, summary statistics, and protocol charts. The README documents the proxy and notification topology; sampled source confirms detector, ingestion, query, and dashboard wiring, but not the internals of those integrations.

Main entry points: [`dashboard/backend/main.py`](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/main.py) (FastAPI routes), [`dashboard/frontend/src/App.js`](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/frontend/src/App.js) (Dashboard app), [`dashboard/backend/routes/alerts.py`](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/routes/alerts.py) (Alert ingestion and reads), [`nginx/nginx.conf`](https://github.com/jadkissa/mpu-project02/blob/main/nginx/nginx.conf) (Nginx proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Detection layers"]
  node_snort["Snort signatures<br/>[snort.lua]"]
  node_ml["Flow ML detector<br/>[detector.py]"]
  node_snortlogs["Snort alert log"]
  node_mllogs["ML alert log<br/>[detector.py]"]
end

subgraph group_ingestion["Alert platform"]
  node_watcher["Alert watcher<br/>[alerts_watcher.py]"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_alert_routes["Alert ingestion and reads<br/>[alerts.py]"]
  node_stats_routes["Statistics queries<br/>[stats.py]"]
  node_schema["Alert validation<br/>[alerts.py]"]
  node_db_access["Database access<br/>[database.py]"]
  node_postgres[("PostgreSQL alerts<br/>[init.sql]")]
end

subgraph group_dashboard["Dashboard"]
  node_frontend["Dashboard app<br/>[App.js]"]
  node_client["API client<br/>[index.js]"]
  node_alert_views["Alert tables"]
  node_stats_views["Stats and chart"]
end

subgraph group_integrations["External integrations"]
  node_nginx["Nginx proxy<br/>[nginx.conf]"]
  node_n8n["n8n workflow"]
end

node_traffic(("Network traffic"))
node_user(("Dashboard user"))
node_telegram(("Telegram"))

node_traffic -->|"inspects packets"| node_snort
node_traffic -->|"extracts flows"| node_ml
node_snort -->|"writes alerts"| node_snortlogs
node_ml -->|"writes alerts"| node_mllogs
node_snortlogs -->|"tails alerts"| node_watcher
node_mllogs -->|"tails alerts"| node_watcher
node_watcher -->|"POSTs alerts"| node_api
node_api -->|"dispatches"| node_alert_routes
node_alert_routes -->|"validates payload"| node_schema
node_alert_routes -->|"queries and writes"| node_db_access
node_stats_routes -->|"queries"| node_db_access
node_db_access -->|"reads and writes"| node_postgres
node_postgres -.->|"LISTEN/NOTIFY"| node_n8n
node_n8n -.->|"sends alerts"| node_telegram
node_user -->|"opens dashboard"| node_nginx
node_nginx -->|"proxies UI"| node_frontend
node_nginx -->|"proxies API"| node_api
node_frontend -->|"requests data"| node_client
node_client -->|"calls endpoints"| node_api
node_api -->|"serves alert data"| node_alert_routes
node_api -->|"serves statistics"| node_stats_routes
node_frontend -->|"renders alerts"| node_alert_views
node_frontend -->|"renders metrics"| node_stats_views

click node_snort "https://github.com/jadkissa/mpu-project02/blob/main/snort/snort.lua"
click node_ml "https://github.com/jadkissa/mpu-project02/blob/main/ml_model/detector.py"
click node_snortlogs "https://github.com/jadkissa/mpu-project02/tree/main/snort"
click node_mllogs "https://github.com/jadkissa/mpu-project02/blob/main/ml_model/detector.py"
click node_watcher "https://github.com/jadkissa/mpu-project02/blob/main/alerts_watcher.py"
click node_api "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/main.py"
click node_alert_routes "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/routes/alerts.py"
click node_stats_routes "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/routes/stats.py"
click node_schema "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/schemas/alerts.py"
click node_db_access "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/database.py"
click node_postgres "https://github.com/jadkissa/mpu-project02/blob/main/init.sql"
click node_frontend "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/frontend/src/App.js"
click node_client "https://github.com/jadkissa/mpu-project02/blob/main/dashboard/frontend/src/api/index.js"
click node_alert_views "https://github.com/jadkissa/mpu-project02/tree/main/dashboard/frontend/src/components"
click node_stats_views "https://github.com/jadkissa/mpu-project02/tree/main/dashboard/frontend/src/components"
click node_nginx "https://github.com/jadkissa/mpu-project02/blob/main/nginx/nginx.conf"

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_snort,node_ml,node_snortlogs,node_mllogs,node_user toneBlue
class node_watcher,node_api,node_alert_routes,node_stats_routes,node_schema,node_db_access,node_postgres toneAmber
class node_frontend,node_client,node_alert_views,node_stats_views toneMint
class node_nginx,node_n8n toneRose
class node_traffic,node_telegram toneIndigo
```

## Components

### Detection layers

- [Snort signatures](https://github.com/jadkissa/mpu-project02/blob/main/snort/snort.lua): `snort/snort.lua`
- [Flow ML detector](https://github.com/jadkissa/mpu-project02/blob/main/ml_model/detector.py): `ml_model/detector.py`
- [Snort alert log](https://github.com/jadkissa/mpu-project02/tree/main/snort): `snort`
- [ML alert log](https://github.com/jadkissa/mpu-project02/blob/main/ml_model/detector.py): `ml_model/detector.py`

### Alert platform

- [Alert watcher](https://github.com/jadkissa/mpu-project02/blob/main/alerts_watcher.py): `alerts_watcher.py`
- [FastAPI routes](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/main.py): `dashboard/backend/main.py`
- [Alert ingestion and reads](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/routes/alerts.py): `dashboard/backend/routes/alerts.py`
- [Statistics queries](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/routes/stats.py): `dashboard/backend/routes/stats.py`
- [Alert validation](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/schemas/alerts.py): `dashboard/backend/schemas/alerts.py`
- [Database access](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/backend/database.py): `dashboard/backend/database.py`
- [PostgreSQL alerts](https://github.com/jadkissa/mpu-project02/blob/main/init.sql): `init.sql`

### Dashboard

- [Dashboard app](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/frontend/src/App.js): `dashboard/frontend/src/App.js`
- [API client](https://github.com/jadkissa/mpu-project02/blob/main/dashboard/frontend/src/api/index.js): `dashboard/frontend/src/api/index.js`
- [Alert tables](https://github.com/jadkissa/mpu-project02/tree/main/dashboard/frontend/src/components): `dashboard/frontend/src/components`
- [Stats and chart](https://github.com/jadkissa/mpu-project02/tree/main/dashboard/frontend/src/components): `dashboard/frontend/src/components`

### External integrations

- [Nginx proxy](https://github.com/jadkissa/mpu-project02/blob/main/nginx/nginx.conf): `nginx/nginx.conf`
- **n8n workflow**

### Other components

- **Network traffic**
- **Dashboard user**
- **Telegram**

## Connections

- Network traffic → Snort signatures: inspects packets
- Network traffic → Flow ML detector: extracts flows
- Snort signatures → Snort alert log: writes alerts
- Flow ML detector → ML alert log: writes alerts
- Snort alert log → Alert watcher: tails alerts
- ML alert log → Alert watcher: tails alerts
- Alert watcher → FastAPI routes: POSTs alerts
- FastAPI routes → Alert ingestion and reads: dispatches
- Alert ingestion and reads → Alert validation: validates payload
- Alert ingestion and reads → Database access: queries and writes
- Statistics queries → Database access: queries
- Database access → PostgreSQL alerts: reads and writes
- PostgreSQL alerts → n8n workflow: LISTEN/NOTIFY
- n8n workflow → Telegram: sends alerts
- Dashboard user → Nginx proxy: opens dashboard
- Nginx proxy → Dashboard app: proxies UI
- Nginx proxy → FastAPI routes: proxies API
- Dashboard app → API client: requests data
- API client → FastAPI routes: calls endpoints
- FastAPI routes → Alert ingestion and reads: serves alert data
- FastAPI routes → Statistics queries: serves statistics
- Dashboard app → Alert tables: renders alerts
- Dashboard app → Stats and chart: renders metrics