# rijul-negi/project-ids architecture

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

- Interactive diagram: https://gitdiagram.com/rijul-negi/project-ids
- Repository: https://github.com/rijul-negi/project-ids

## Overview

This is a hybrid network intrusion-detection system with configurable TCP honeypots and a Flask monitoring dashboard. Its principal workflow captures packets, builds and exports flows, checks signatures, then applies whitelist filtering and ML classification before queuing alerts for the dashboard stream. The launcher starts these workers concurrently. The README documents dashboard and monitoring capabilities beyond the sampled HTML; source excerpts show the backend stream and routes, but not the dashboard implementation. Note that main.py imports `sniffer` while the tree lists `Sniffer.py`, which may affect imports on case-sensitive systems.

Main entry points: [`main.py`](https://github.com/rijul-negi/project-ids/blob/main/main.py) (Worker Launcher), [`server.py`](https://github.com/rijul-negi/project-ids/blob/main/server.py) (Flask Event Server), [`Sniffer.py`](https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py) (Alert Queue), [`infer.py`](https://github.com/rijul-negi/project-ids/blob/main/infer.py) (ML Classification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Traffic Analysis"]
  node_launcher["Worker Launcher<br/>[main.py]"]
  node_packet["Packet Capture<br/>[Sniffer.py]"]
  node_flow["Flow Processing<br/>[Sniffer.py]"]
end

subgraph group_detection["Detection"]
  node_signature["Signature Matching<br/>[sign.py]"]
  node_rules["Snort Rules"]
  node_classifier["ML Classification<br/>[infer.py]"]
  node_model["XGBoost Model<br/>[v5_model.json]"]
  node_whitelist["IP Whitelist<br/>[whitelist.json]"]
end

subgraph group_deception["Honeypot"]
  node_honeypots["Port Honeypots<br/>[honeypot.py]"]
end

subgraph group_delivery["Alerts and Dashboard"]
  node_alertqueue["Alert Queue<br/>[Sniffer.py]"]
  node_server["Flask Event Server<br/>[server.py]"]
  node_dashboard["Web Dashboard<br/>[dashboard.html]"]
end

node_operator(("Dashboard User"))
node_network(("Network Clients"))

node_launcher -->|"starts capture"| node_packet
node_launcher -->|"starts workers"| node_flow
node_launcher -->|"starts worker"| node_classifier
node_launcher -->|"starts listeners"| node_honeypots
node_launcher -->|"starts server"| node_server
node_packet -->|"updates flows"| node_flow
node_packet -->|"checks packets"| node_signature
node_signature -->|"loads rules"| node_rules
node_flow -->|"queues flow data"| node_alertqueue
node_alertqueue -->|"consumes flows"| node_classifier
node_classifier -->|"loads model"| node_model
node_classifier -->|"loads trusted IPs"| node_whitelist
node_classifier -->|"queues results"| node_alertqueue
node_launcher -->|"shares alert queue"| node_alertqueue
node_honeypots -->|"queues hit alerts"| node_alertqueue
node_network -->|"connects to ports"| node_honeypots
node_launcher -->|"configures queue"| node_server
node_server -->|"reads alerts"| node_alertqueue
node_server -->|"serves page"| node_dashboard
node_operator -->|"views monitoring"| node_dashboard
node_server -->|"serves whitelist"| node_whitelist
node_dashboard -.->|"opens event stream"| node_server

click node_launcher "https://github.com/rijul-negi/project-ids/blob/main/main.py"
click node_packet "https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py"
click node_flow "https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py"
click node_signature "https://github.com/rijul-negi/project-ids/blob/main/sign.py"
click node_rules "https://github.com/rijul-negi/project-ids/blob/main/snort3-community.rules"
click node_classifier "https://github.com/rijul-negi/project-ids/blob/main/infer.py"
click node_model "https://github.com/rijul-negi/project-ids/blob/main/v5_model.json"
click node_whitelist "https://github.com/rijul-negi/project-ids/blob/main/whitelist.json"
click node_honeypots "https://github.com/rijul-negi/project-ids/blob/main/honeypot.py"
click node_alertqueue "https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py"
click node_server "https://github.com/rijul-negi/project-ids/blob/main/server.py"
click node_dashboard "https://github.com/rijul-negi/project-ids/blob/main/dashboard.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_launcher,node_packet,node_flow,node_operator,node_network toneBlue
class node_signature,node_rules,node_classifier,node_model,node_whitelist toneAmber
class node_honeypots toneMint
class node_alertqueue,node_server,node_dashboard toneRose
```

## Components

### Traffic Analysis

- [Worker Launcher](https://github.com/rijul-negi/project-ids/blob/main/main.py): `main.py`
- [Packet Capture](https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py): `Sniffer.py`
- [Flow Processing](https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py): `Sniffer.py`

### Detection

- [Signature Matching](https://github.com/rijul-negi/project-ids/blob/main/sign.py): `sign.py`
- [Snort Rules](https://github.com/rijul-negi/project-ids/blob/main/snort3-community.rules): `snort3-community.rules`
- [ML Classification](https://github.com/rijul-negi/project-ids/blob/main/infer.py): `infer.py`
- [XGBoost Model](https://github.com/rijul-negi/project-ids/blob/main/v5_model.json): `v5_model.json`
- [IP Whitelist](https://github.com/rijul-negi/project-ids/blob/main/whitelist.json): `whitelist.json`

### Honeypot

- [Port Honeypots](https://github.com/rijul-negi/project-ids/blob/main/honeypot.py): `honeypot.py`

### Alerts and Dashboard

- [Alert Queue](https://github.com/rijul-negi/project-ids/blob/main/Sniffer.py): `Sniffer.py`
- [Flask Event Server](https://github.com/rijul-negi/project-ids/blob/main/server.py): `server.py`
- [Web Dashboard](https://github.com/rijul-negi/project-ids/blob/main/dashboard.html): `dashboard.html`

### Other components

- **Dashboard User**
- **Network Clients**

## Connections

- Worker Launcher → Packet Capture: starts capture (evidence: `main.py`)
- Worker Launcher → Flow Processing: starts workers (evidence: `main.py`)
- Worker Launcher → ML Classification: starts worker (evidence: `main.py`)
- Worker Launcher → Port Honeypots: starts listeners (evidence: `main.py`)
- Worker Launcher → Flask Event Server: starts server (evidence: `main.py`)
- Packet Capture → Flow Processing: updates flows (evidence: `Sniffer.py`)
- Packet Capture → Signature Matching: checks packets (evidence: `Sniffer.py`)
- Signature Matching → Snort Rules: loads rules (evidence: `sign.py`)
- Flow Processing → Alert Queue: queues flow data (evidence: `Sniffer.py`)
- Alert Queue → ML Classification: consumes flows
- ML Classification → XGBoost Model: loads model (evidence: `infer.py`)
- ML Classification → IP Whitelist: loads trusted IPs (evidence: `infer.py`)
- ML Classification → Alert Queue: queues results
- Worker Launcher → Alert Queue: shares alert queue (evidence: `main.py`)
- Port Honeypots → Alert Queue: queues hit alerts (evidence: `honeypot.py`)
- Network Clients → Port Honeypots: connects to ports (evidence: `honeypot.py`)
- Worker Launcher → Flask Event Server: configures queue (evidence: `main.py`)
- Flask Event Server → Alert Queue: reads alerts (evidence: `server.py`)
- Flask Event Server → Web Dashboard: serves page (evidence: `server.py`)
- Dashboard User → Web Dashboard: views monitoring (evidence: `README.md`)
- Flask Event Server → IP Whitelist: serves whitelist (evidence: `server.py`)
- Web Dashboard → Flask Event Server: opens event stream
