# 22bet10009-shuvam/packet_anomaly_detector architecture

> Architecture diagram of the GitHub repository 22bet10009-shuvam/packet_anomaly_detector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/22bet10009-shuvam/packet_anomaly_detector
- Repository: https://github.com/22bet10009-shuvam/packet_anomaly_detector

## Overview

This is a **single-node desktop application** (Python) that performs **live network packet capture** and runs **intrusion detection** on the captured traffic using:
- **Rule-based detection** (signatures/heuristics like SYN floods, port scans, keywords)
- **ML-based anomaly detection** (online baseline/clustering; “adaptive anomaly detection”)
…and then presents results in a **professional GUI** with:
- live packet feed
- alerts + severity
- explainable ML deviations
- mitigation/prevention suggestions
- alert history + export (CSV)
- configurable thresholds via YAML

##### File structure analysis (map folders → architectural components)
From the tree:

##### Entrypoints / Application bootstrap
- `src/ids_app/__main__.py` → `python -m ids_app` entrypoint
- `src/ids_app/app.py` → likely wires together UI + sniffer + detectors + config

##### Configuration
- `src/ids_app/config/config.yaml` → user-tunable thresholds, ML settings, keyword rules
- `src/ids_app/core/config.py` → config loader/validator and access object

##### Core runtime (capture + detect + model + suggestions)
- `src/ids_app/core/sniffer.py` → live packet capture (Npcap/scapy/pyshark-style)
- `src/ids_app/core/detector.py` → rule-based detection pipeline
- `src/ids_app/core/ml_detector.py` → ML anomaly model, baseline updates, scoring, explanations
- `src/ids_app/core/models.py` → domain models: Packet, Alert, HistoryEntry, etc. (and maybe DTOs)
- `src/ids_app/core/suggestions.py` → mapping alert type/severity → mitigation steps

##### UI layer (desktop GUI)
- `src/ids_app/ui/main_window.py` → GUI composition: packet table, alerts panel, controls
- `src/ids_app/ui/theme.qss` → styling (Qt stylesheet strongly implied)

##### Build/Deps
- `requirements.txt` → runtime dependencies (capture + GUI + ML stack)
- OS constraint: Windows + admin + Npcap (from README)

**Architectural pattern implied:** classic layered design:
- **UI layer** (presentation)
- **Core/services** (capture + detection + recommendation)
- **Config + models** (shared foundation)
No separate backend/server is evident; everything runs in one process.

##### README insights to explicitly include
Key runtime responsibilities to reflect:
- **Live packet feed** (high-throughput stream)
- **Detection alerts** + **alert history**
- **ML explainability** (“top feature deviations and anomaly score context”)
- **Export dataset (CSV)**
- **Interface selection + start/stop capture**
- **YAML-configured thresholds**
- **Windows + Npcap dependency**

- **control flow** (start/stop, adapter selection)
- **data flow** (packets → features → alerts → UI/history/export)
- **stateful ML baseline** (adaptive model updated over time)

##### Network Interface(s) (Ethernet/Wi‑Fi adapters)

**Application (Python process: `ids_app`)**
##### Config Loader + Config Object (`core/config.py` reading `config/config.yaml`)
13. **Export Service (CSV)** (even if implemented inside UI/core, show it as a distinct capability because it’s a user-facing subsystem)

**Storage (likely local, lightweight)**
14. **In-memory Alert History / Dataset** (if there’s no DB in tree, model it as in-memory + exported file)

##### Important design principles/patterns
- **Single-process modular architecture** (UI + Core in same runtime)
- **Streaming pipeline** (continuous packet ingestion)
- **Two detection strategies in parallel** (rule + ML)
- **Stateful ML** (online learning / clustering baseline)
- **Explainability path** (ML detector emits “top feature deviations” not just a score)
- **Config-driven behavior** (YAML controls thresholds and rules)

##### Relevant tech/frameworks
Based on cues:
- **Python 3.10+**
- **Npcap** (Windows packet capture driver)
- **Qt-style UI** implied by `theme.qss` (so likely PyQt/PySide). If requirements confirm later, annotate as “PySide6/PyQt”.

##### “Separate into as many components as possible” (without overthinking)
For maximum accuracy/detail, explicitly split these as separate components even if implemented together:
- **Capture** vs **Decode/Parse** vs **Feature extraction**
- **Rule detection** vs **ML detection**
- **Alert aggregation** vs **Alert history store**
- **Suggestion mapping** vs **UI rendering**

##### Level 0 (Context): User + Network + Windows/Npcap ↔ “IDS Live Monitor App”
2. **Level 1 (Containers within app):** UI ↔ Core (Sniffer + Detection + Suggestions) ↔ Config/Export

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Level 0 — Context
  %% =========================
  subgraph "Level 0 — Context (Single-node Desktop IDS)"
    direction TB

    User["User / Analyst"]:::external
    NIC["Network Interface(s)\n(Ethernet / Wi‑Fi)"]:::external
    Win["Windows OS\n(Admin privileges)"]:::external
    Npcap["Npcap Driver\n(Packet capture provider)"]:::external

    AppCtx["IDS Live Monitor App\n(Python single-process)"]:::app
  end

  NIC -->|"raw_packets"| Npcap
  Win -->|"hosts"| Npcap
  Npcap -->|"raw_packets"| AppCtx
  User -->|"controls_start_stop_select_export"| AppCtx
  AppCtx -->|"live_view_alerts_reports"| User

  %% =========================
  %% Level 1/2 — Containers & Components
  %% =========================
  subgraph "Level 1/2 — ids_app Process (Modules & Runtime Dataflow)"
    direction TB

    %% ---- Bootstrap / Wiring ----
    subgraph "Bootstrap & Wiring"
      direction TB
      Entry["Entrypoint\n(python -m ids_app)"]:::bootstrap
      Orchestrator["App Orchestrator / Wiring"]:::bootstrap
      Entry -->|"init_app"| Orchestrator
    end

    %% ---- Configuration ----
    subgraph "Configuration"
      direction TB
      YAML["YAML Config\n(thresholds, rules, ML settings)"]:::artifact
      ConfigLoader["Config Loader / Validator\n(Config object)"]:::config
      YAML -->|"read_parse_validate"| ConfigLoader
    end

    %% ---- UI Layer ----
    subgraph "UI Layer (Desktop GUI)"
      direction TB
      MainWindow["Main Window\n(packet table, alerts, controls)"]:::ui
      Theme["Qt Stylesheet Theme"]:::uiArtifact
      ExportSvc["Export Service\n(CSV)"]:::ui
      Theme -->|"style_applied"| MainWindow
      MainWindow -->|"export_request"| ExportSvc
    end

    %% ---- Core Pipeline ----
    subgraph "Core Runtime Pipeline"
      direction TB

      Sniffer["Packet Sniffer / Capture Service"]:::core
      Parse["Packet Parsing / Decode"]:::core
      Feat["Feature Extraction"]:::core

      subgraph "Parallel Detection Engines"
        direction TB
        RuleDet["Rule-based Detector\n(signatures/heuristics)"]:::core
        MLDet["ML Anomaly Detector\n(adaptive baseline + explainability)"]:::ml
        MLState[("Stateful ML Baseline\n(online updates)")]:::state
        MLDet -->|"update_baseline"| MLState
        MLState -->|"baseline_state"| MLDet
      end

      Models["Domain Models\n(Packet, Alert, HistoryEntry)"]:::model
      Suggest["Suggestions / Mitigation Engine"]:::core

      Sniffer -->|"captured_packets"| Parse
      Parse -->|"Packet"| Models
      Parse -->|"parsed_packet"| Feat
      Feat -->|"packet_features"| RuleDet
      Feat -->|"FeatureVector"| MLDet

      RuleDet -->|"Alert(type,severity,evidence)"| Models
      MLDet -->|"Alert(anomaly_score,top_deviations,context)"| Models

      Models -->|"alert_metadata"| Suggest
      Suggest -->|"Suggestion(guidance)"| MainWindow
    end

    %% ---- Local State / History & Artifacts ----
    subgraph "Local State & Outputs"
      direction TB
      History[("In-memory Alert History\n+ dataset buffer")]:::state
      CSV["CSV File\n(exported alert dataset)"]:::artifact
    end

    %% ---- Cross-cutting wiring ----
    Orchestrator -->|"load_config"| ConfigLoader
    ConfigLoader -->|"Config"| Sniffer
    ConfigLoader -->|"Config"| RuleDet
    ConfigLoader -->|"Config"| MLDet
    ConfigLoader -->|"Config"| Suggest

    Orchestrator -->|"create_show_ui"| MainWindow
    Orchestrator -->|"start_pipeline"| Sniffer

    %% UI control flow
    MainWindow -->|"start_stop_capture"| Sniffer
    MainWindow -->|"select_interface"| Sniffer

    %% Live feed + alerts into UI
    Sniffer -->|"live_packet_feed"| MainWindow
    Models -->|"alert_stream"| MainWindow

    %% Alert history updates
    Models -->|"history_entry"| History
    History -->|"history_view"| MainWindow

    %% Export path
    History -->|"dataset_for_export"| ExportSvc
    ExportSvc -->|"write_csv"| CSV
  end

  %% Tie context app box to internal bootstrap
  AppCtx -->|"runs"| Entry

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click Entry "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/__main__.py"
  click Orchestrator "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/app.py"
  click YAML "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/config/config.yaml"
  click ConfigLoader "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/config.py"
  click Sniffer "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/sniffer.py"
  click RuleDet "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/detector.py"
  click MLDet "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/ml_detector.py"
  click Models "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/models.py"
  click Suggest "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/core/suggestions.py"
  click MainWindow "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/ui/main_window.py"
  click Theme "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/src/ids_app/ui/theme.qss"
  click AppCtx "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click Win "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click Npcap "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click NIC "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click User "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click ExportSvc "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click CSV "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click History "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click Parse "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click Feat "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click MLState "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/README.md"
  click AppCtx "https://github.com/22bet10009-shuvam/packet_anomaly_detector/blob/main/requirements.txt"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ECEFF4,stroke:#4C566A,stroke-width:1px,color:#2E3440;
  classDef app fill:#D8DEE9,stroke:#2E3440,stroke-width:2px,color:#2E3440;
  classDef bootstrap fill:#E5E9F0,stroke:#5E81AC,stroke-width:2px,color:#2E3440;

  classDef ui fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px,color:#1B4F72;
  classDef uiArtifact fill:#EBF5FB,stroke:#2E86C1,stroke-width:1.5px,color:#1B4F72;

  classDef core fill:#D5F5E3,stroke:#239B56,stroke-width:2px,color:#145A32;
  classDef ml fill:#D5F5E3,stroke:#1E8449,stroke-width:2px,color:#0B5345;

  classDef model fill:#E8F8F5,stroke:#16A085,stroke-width:2px,color:#0E6251;

  classDef config fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px,color:#4A235A;
  classDef artifact fill:#F5EEF8,stroke:#7D3C98,stroke-width:2px,color:#4A235A;

  classDef state fill:#FDEBD0,stroke:#B9770E,stroke-width:2px,color:#7E5109;
```
