# aadilsalimm/network_attack_detection_miniproject architecture

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

- Interactive diagram: https://gitdiagram.com/aadilsalimm/network_attack_detection_miniproject
- Repository: https://github.com/aadilsalimm/network_attack_detection_miniproject

## Overview

##### Project type + purpose (from README + tree)
This is a **single-repo Python prototype** that performs **real-time DoS detection and mitigation** by:
- **Capturing live network traffic** (Scapy-based capture)
- **Running ML inference** (scikit-learn model persisted as a `.joblib`)
- **Logging events** (SQLite DB file `database/db/log.db` accessed via `database/db_ops.py`)
- **(Optionally) presenting a web UI** (Flask app + Jinja templates + static CSS)

The repo structure indicates a **modular monolith** (not microservices): clear “modules” by folder, wired together by `app.py`.

##### Orchestration / Entry point
- `app.py`
Likely the main Flask app and/or the runtime orchestrator that triggers capture → predict → mitigate → log, and serves pages.

##### Network capture
- `network_capture/capture.py`
Responsible for sniffing packets (Scapy), aggregating flows, or extracting raw stats.

##### ML prediction
- `prediction_module/make_prediction.py`
- `prediction_module/models/rfClassifier#temp.joblib`
Loads the trained model, transforms features, outputs “DoS / benign” (and maybe confidence).

##### Mitigation
- `mitigation/mitigate.py`

##### Persistence / logging
- `database/db_ops.py`
- `database/db/log.db` (SQLite file)
Responsible for writing and reading detection/mitigation logs.

##### Web UI
- `templates/home.html`, `templates/log_page.html`
- `static/styles/*.css`
Flask-rendered UI: likely home/dashboard + log viewer.

##### Dependencies / environment
- `requirements.txt`

##### Flask Web App → Admin Browser (HTML)

Purpose: show module-level structure (very grounded in your repo).
Folder as a component with its key file(s):
- `network_capture` (capture)
- `prediction_module` (predict + model loading)
- `mitigation` (actions)
- `database` (db_ops + sqlite)
- `templates/static` (presentation)
- `app.py` (composition/root)

This is where you add “interfaces” (functions or calls) even if informal:
- `capture_packets()` / `extract_features()`
- `make_prediction(features)`
- `mitigate(src_ip, attack_type)`
- `insert_log(event)` / `fetch_logs()`

##### Data transformations
- **Raw packets** (Scapy) → **Derived features** (pandas/numpy) → **Model input vector** → **Prediction label/score**

##### State + storage
- **SQLite file** as the single durable state (`log.db`)

##### Control flow (real-time loop)
An always-on loop:
- sniff → aggregate window → predict → (if attack) mitigate → log → repeat

##### UI flow
- Browser requests `/` → renders `home.html`
- Browser requests `/logs` (or similar) → DB read → renders `log_page.html`

##### External dependencies
“callouts” (small notes) on relevant components:
- Scapy
- Prediction: scikit-learn + joblib model
- Feature processing: pandas/numpy
- Web: Flask + Jinja templates
- DB: SQLite

This gives maximum clarity and separates concerns cleanly while staying faithful to the codebase structure.

- [ ] Every folder in the tree is represented somewhere (at least Level 2)
- [ ] `app.py` is explicitly the orchestrator and UI entrypoint (if that’s the case)
- [ ] Model artifact (`.joblib`) is shown as a dependency of prediction
- [ ] SQLite `log.db` is shown as the persistent store
- [ ] Mitigation affects an **external** system boundary (OS/network stack)
- [ ] Data flow includes: packets → features → prediction → mitigation/logging
- [ ] UI pages map to templates (`home.html`, `log_page.html`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 0 - System Context
    %% =========================
    subgraph "Level 0 — System Context"
        Admin["Operator / Admin"]:::external
        Browser["Web Browser"]:::ui

        NetIF["Monitored Network Interface\n(Live Traffic)"]:::external
        OSFW["Host OS Networking Stack / Firewall"]:::external

        System["DoS Detection & Mitigation System\n(Python Prototype Repo)"]:::system
    end

    Admin -->|"uses"| Browser
    Browser -->|"HTTP requests (/, /logs)"| System
    NetIF -->|"Network packets (live)"| System
    System -->|"Mitigation actions\n(block/rate-limit)"| OSFW
    System -->|"HTML responses (dashboard, logs)"| Browser

    %% =========================
    %% Level 1 - Containers (Logical runtime)
    %% =========================
    subgraph "Level 1 — Containers / Runtime View (Logical)"
        subgraph "Python Runtime (single repo; modular monolith)"
            App["Flask Web App + Orchestrator\n(app.py)"]:::py

            subgraph "Real-time Detection Pipeline (always-on loop)"
                Capture["Traffic Capture Worker\n(Scapy sniff)"]:::py
                Features["Feature Extraction / Aggregation\n(pandas/numpy)"]:::py
                Predict["Prediction Engine\n(scikit-learn inference)"]:::py
                Decision{"Prediction == attack?"}:::decision
                Mitigate["Mitigation Engine\n(apply actions)"]:::py
            end

            DBops["DB Ops / Persistence API"]:::py
            DB[("SQLite Log DB\nlog.db")]:::db

            subgraph "Web UI (Flask + Jinja)"
                THome["Template: home.html"]:::ui
                TLogs["Template: log_page.html"]:::ui
                CSSHome["CSS: home.css"]:::ui
                CSSLogs["CSS: log_page.css"]:::ui
            end

            Model[("Model Artifact\n.joblib")]:::artifact
        end

        OfflineTrain["Model Training (offline)\n(not in repo)"]:::offline
    end

    %% Runtime pipeline flows
    App -->|"starts / coordinates"| Capture
    Capture -->|"Raw packets (scapy)"| Features
    Features -->|"Flow stats / features\n(numpy/pandas)"| Predict
    Predict -->|"Model input vector"| Model
    Predict -->|"Prediction: {label, score, src_ip}"| Decision

    Decision -->|"yes: attack"| Mitigate
    Decision -->|"no: benign"| DBops

    Mitigate -->|"Mitigation action:\nblock src_ip / rate limit"| OSFW
    Mitigate -->|"Log mitigation event"| DBops
    Predict -->|"Log prediction event"| DBops

    DBops -->|"SQL INSERT/SELECT"| DB

    %% Web UI flows
    App -->|"renders /"| THome
    App -->|"renders /logs"| TLogs
    THome -->|"uses"| CSSHome
    TLogs -->|"uses"| CSSLogs
    App -->|"SQL SELECT (fetch logs)"| DBops

    %% Offline -> artifact
    OfflineTrain -.->|"exports persisted model"| Model

    %% =========================
    %% Level 2 - Component (Codebase modules)
    %% =========================
    subgraph "Level 2 — Codebase Component View (Modules / Files)"
        App2["app.py\n(Composition root: routes + runtime loop wiring)"]:::py
        Cap2["network_capture/capture.py\n(sniff + capture_packets())"]:::py
        Pred2["prediction_module/make_prediction.py\n(make_prediction(features))"]:::py
        Model2[("prediction_module/models/*.joblib\n(rfClassifier...)")]:::artifact
        Mit2["mitigation/mitigate.py\n(mitigate(src_ip, attack_type))"]:::py
        DBOps2["database/db_ops.py\n(insert_log(), fetch_logs())"]:::py
        DB2[("database/db/log.db\n(SQLite)")]:::db

        HomeHTML["templates/home.html"]:::ui
        LogsHTML["templates/log_page.html"]:::ui
        HomeCSS["static/styles/home.css"]:::ui
        LogsCSS["static/styles/log_page.css"]:::ui

        Reqs["requirements.txt\n(Scapy, Flask, sklearn, pandas, numpy, SQLite)"]:::deps
    end

    %% Component interactions (module-level)
    App2 -->|"calls capture_packets()"| Cap2
    Cap2 -->|"outputs derived features"| Pred2
    Pred2 -->|"loads model (joblib)"| Model2
    Pred2 -->|"if attack: calls mitigate()"| Mit2
    Pred2 -->|"logs prediction"| DBOps2
    Mit2 -->|"logs mitigation"| DBOps2
    DBOps2 -->|"reads/writes"| DB2

    App2 -->|"renders route /"| HomeHTML
    App2 -->|"renders route /logs"| LogsHTML
    HomeHTML -->|"links"| HomeCSS
    LogsHTML -->|"links"| LogsCSS
    App2 -->|"fetch_logs()"| DBOps2

    %% =========================
    %% Click events (mapped paths)
    %% =========================
    click App "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/app.py"
    click Capture "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/network_capture/capture.py"
    click Predict "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/prediction_module/make_prediction.py"
    click Model "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/prediction_module/models/rfClassifier#temp.joblib"
    click Mitigate "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/mitigation/mitigate.py"
    click DBops "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/database/db_ops.py"
    click DB "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/database/db/log.db"
    click THome "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/templates/home.html"
    click TLogs "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/templates/log_page.html"
    click CSSHome "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/static/styles/home.css"
    click CSSLogs "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/static/styles/log_page.css"

    click App2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/app.py"
    click Cap2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/network_capture/capture.py"
    click Pred2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/prediction_module/make_prediction.py"
    click Model2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/prediction_module/models/rfClassifier#temp.joblib"
    click Mit2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/mitigation/mitigate.py"
    click DBOps2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/database/db_ops.py"
    click DB2 "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/database/db/log.db"
    click HomeHTML "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/templates/home.html"
    click LogsHTML "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/templates/log_page.html"
    click HomeCSS "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/static/styles/home.css"
    click LogsCSS "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/static/styles/log_page.css"
    click Reqs "https://github.com/aadilsalimm/network_attack_detection_miniproject/blob/main/requirements.txt"

    %% =========================
    %% Styles
    %% =========================
    classDef system fill:#1f6feb,stroke:#0b3d91,stroke-width:2px,color:#ffffff
    classDef py fill:#0b3d91,stroke:#072a63,stroke-width:1.5px,color:#ffffff
    classDef db fill:#1f8f4a,stroke:#0f5a2c,stroke-width:2px,color:#ffffff
    classDef external fill:#f59e0b,stroke:#9a5b00,stroke-width:2px,color:#111827
    classDef ui fill:#9ca3af,stroke:#4b5563,stroke-width:1.5px,color:#111827
    classDef decision fill:#ef4444,stroke:#7f1d1d,stroke-width:2px,color:#ffffff
    classDef artifact fill:#7c3aed,stroke:#4c1d95,stroke-width:2px,color:#ffffff
    classDef offline fill:#e5e7eb,stroke:#6b7280,stroke-width:1.5px,color:#111827
    classDef deps fill:#60a5fa,stroke:#1d4ed8,stroke-width:1.5px,color:#111827
```
