# rathalos1234/ai-ids architecture

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

- Interactive diagram: https://gitdiagram.com/rathalos1234/ai-ids
- Repository: https://github.com/rathalos1234/ai-ids

## Overview

##### Project type and purpose
- Full-stack network intrusion detection system (IDS)
- Python CLI & long-running service for live capture, training, verification, monitoring
- Vue.js single-page app for real-time alerts, logs, firewall controls
- Docker-Compose deployment with Nginx reverse proxy

##### File structure (key components)
- Top-level Python modules:
– main.py: CLI entrypoint (train, verify, monitor)
– packet_processor.py → feature engineering
– anomaly_detector.py → IsolationForest scoring
– signature_engine.py → rule-based signature hits
– network_monitor.py, firewall.py → live-capture loop, iptables blocking
– api.py → REST/WebSocket API server (health, alert stream, banlist, settings)
– webdb.py → lightweight persistent store (bans, settings)
- “models/iforest.joblib”: serialized trained model bundle
- “data/rolling.parquet”: optional Parquet store of engineered rows
- UI folder (“ui/…”): Vue.js app (App.vue, router.js, api.js, views/*.vue)
- docker-compose.yml, nginx.conf → container definitions, routing
- ops/*.service & scripts/ → systemd units & helper scripts for install, backup, retention
- tests/ & tests/ui/ → Python pytest modules + Playwright end-to-end UI tests

##### README for architectural patterns
- Pipeline stages: capture → feature-engineer → train → save/verify → monitor
- SignatureEngine as plug-in stage in monitoring loop
- REST and event-stream API feeding UI
- Optional firewall bridge using Linux iptables
- Deployment via Docker + Compose behind Nginx

##### Main components
a. Network Interface (eth0 or lo)
b. Python Backend Service (container):
- Packet Capture + Processor
- Feature Engineering Module
- Anomaly Detector (IsolationForest)
- Signature Engine (rule evaluator)
- Local Persistence: Model Store, Parquet Store, WebDB
- REST & WebSocket API Endpoints
- Firewall Controller (iptables)
c. Vue.js Frontend (container):
- HTTP(S) & WebSocket client
- UI Views: Dashboard, Alerts, Logs, Settings, BanList
d. Nginx Reverse Proxy (container or host):
- TLS termination (optional)
- HTTP routing → API vs. static UI assets
e. External Systems:
- Systemd services for backup/retention timers
- CI/CD pipeline (GitHub Actions → Docker image → SSH deploy)
- Linux host firewall subsystem (iptables)

##### Relationships and data flows
- Packets flow from Network Interface → Packet Processor → Feature Engineering →
→ Anomaly Detector & Signature Engine → generate Alert/Signature events
- Events pushed to API’s event stream (WebSocket or Server-Sent Events)
- Frontend subscribes to event stream & polls REST endpoints for history, logs, banlist
- User actions in UI (e.g., “Block IP”) → REST API call → Firewall Controller → iptables → WebDB updated
- Training & verification invoked via CLI (main.py) reading/writing model bundles in “models/”
- Optional Parquet persistence writes to “data/rolling.parquet” for offline retraining

##### Architectural patterns and principles
- Modular pipeline: decoupled processing stages (processor → anomaly → signatures)
- Separation of concerns: CLI vs. long-running service vs. UI vs. persistence
- Single backend monolith (in one container) exposing microservice-style API
- Event-driven UI via WebSocket/SSE for real-time alerts
- Infrastructure as code: Compose + systemd units + setup scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Network
    NI["Network Interface"]:::external

    %% Nginx Reverse Proxy
    NG["Nginx Reverse Proxy"]:::external

    %% Backend Container
    subgraph "Backend Container" 
        direction TB
        CLI["Python CLI Entrypoint\n(main.py)"]:::backend
        NM["Packet Capture Loop & Network Monitor\n(network_monitor.py)"]:::backend
        PP["Feature Engineering Module\n(packet_processor.py)"]:::backend
        AD["Anomaly Detector\n(anomaly_detector.py)"]:::backend
        SE["Signature Engine\n(signature_engine.py)"]:::backend
        API["REST & WebSocket API Server\n(api.py)"]:::backend
        FW["Firewall Controller\n(firewall.py)"]:::backend

        %% Data Stores
        MS["Model Store\n(models/iforest.joblib)"]:::datastore
        PS["Parquet Data Store\n(data/rolling.parquet)"]:::datastore
        DB["Lightweight Persistent Store\n(webdb.py)"]:::datastore

        %% Config
        CFG["Configuration & Validation\n(config.ini,\nconfig_validation.py)"]:::backend
    end

    %% Frontend Container
    subgraph "Frontend Container"
        direction TB
        UI["Vue.js Frontend App"]:::frontend
    end

    %% Host & External Systems
    subgraph "Host & External"
        direction TB
        OSFW["OS Firewall Subsystem\n(iptables)"]:::external
        SYS["Systemd Services & Timers\n(ops/*.service)"]:::external
        CI["CI/CD Pipeline\n(.github/workflows)"]:::external
    end

    %% Flows
    NI -->|"raw packets"| NM
    NM -->|"packets"| PP
    PP -->|"features"| AD
    PP -->|"features"| SE
    AD -->|"anomaly events"| API
    SE -->|"signature events"| API

    API -->|"SSE/WebSocket\nJSON event stream"| UI
    API -->|"JSON over HTTP\nhistory, logs, banlist"| UI

    UI -->|"REST API calls\n(block IP, settings)"| API
    API -->|"execute block"| FW
    FW -->|"iptables commands"| OSFW
    FW -->|"record ban"| DB

    CLI -->|"train, verify, monitor"| AD
    CLI -->|"read/write model"| MS
    CLI -->|"read/write parquet"| PS

    PS -->|"offline retrain data"| CLI

    API -->|"config read"| CFG
    CLI -->|"config read"| CFG

    %% Infrastructure flows
    CI -->|"build & deploy images"| NG
    NG -->|"route HTTP(S) to frontend"| UI
    NG -->|"route /api to backend"| API
    SYS -->|"manage containers & services"| NG
    SYS -->|"manage backend service"| CLI

    %% Click events
    click CLI "https://github.com/rathalos1234/ai-ids/blob/main/main.py"
    click NM "https://github.com/rathalos1234/ai-ids/blob/main/network_monitor.py"
    click PP "https://github.com/rathalos1234/ai-ids/blob/main/packet_processor.py"
    click AD "https://github.com/rathalos1234/ai-ids/blob/main/anomaly_detector.py"
    click SE "https://github.com/rathalos1234/ai-ids/blob/main/signature_engine.py"
    click API "https://github.com/rathalos1234/ai-ids/blob/main/api.py"
    click FW "https://github.com/rathalos1234/ai-ids/blob/main/firewall.py"
    click DB "https://github.com/rathalos1234/ai-ids/blob/main/webdb.py"
    click MS "https://github.com/rathalos1234/ai-ids/blob/main/models/iforest.joblib"
    click PS "https://github.com/rathalos1234/ai-ids/blob/main/data/rolling.parquet"
    click CFG "https://github.com/rathalos1234/ai-ids/blob/main/config.ini"
    click NG "https://github.com/rathalos1234/ai-ids/blob/main/nginx.conf"
    click CI "https://github.com/rathalos1234/ai-ids/blob/main/.github/workflows/ci_pipeline.yml"
    click SYS "https://github.com/rathalos1234/ai-ids/blob/main/ops/ai-ids-api.service"
    click SYS "https://github.com/rathalos1234/ai-ids/blob/main/ops/ai-ids-ui.service"
    click SYS "https://github.com/rathalos1234/ai-ids/blob/main/ops/ai-ids-backup.service"
    click SYS "https://github.com/rathalos1234/ai-ids/blob/main/ops/ai-ids-retention.service"
    click SYS "https://github.com/rathalos1234/ai-ids/blob/main/ops/nginx.conf"

    classDef backend fill:#E0F7FA,stroke:#006064
    classDef datastore fill:#E8F5E9,stroke:#1B5E20
    classDef frontend fill:#FFF3E0,stroke:#E65100
    classDef external fill:#ECEFF1,stroke:#455A64
```
