# bittb/network-intrusion-detection-system architecture

> Architecture diagram of the GitHub repository bittb/network-intrusion-detection-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bittb/network-intrusion-detection-system
- Repository: https://github.com/bittb/network-intrusion-detection-system

## Overview

##### What this project is (from README + tree)
This repo is a **Network Intrusion Detection System (NIDS)** with:
- A **Python detection engine** (`nids1.py`, `nids2.py`) that sniffs/ingests network traffic and performs:
- **signature-based detection** (using `nids_signatures.db`)
- **anomaly/ML-based detection** (per README; confirm in code/requirements)
- A **UI dashboard** (React-style file set: `App.js`, `Dashboard.js`, `Logs.js`, `AnomaliesTable.js`, `Settings.js`, `AnalyticsContext.js`, CSS files)
- Some form of **backend/API layer** (`backend/` directory + `api.js` in the root) that the UI calls to fetch status/logs/anomalies and push config.
- A **database + schema** (`schema.sql`, `nids_signatures.db`) used for signatures and/or logging.

##### How to read the file structure into architecture components
Files/directories into *diagrammable* components:

##### Frontend (SPA dashboard)
Evidence: `App.js`, `index.js`, `index.html`, many UI components and CSS.
Key subcomponents to show (don’t just label “frontend”—split it):
- **App Shell / Router**: `App.js`, `Home.js`, `Navbar.js`, `Footer.js`
- **Dashboard views**:
- **Dashboard**: `Dashboard.js`, `StatusCard.js`
- **Logs**: `Logs.js`
- **Anomalies**: `AnomaliesTable.js` (+ `Anomalies.css`)
- **Settings/Configuration**: `Settings.js`, `ConfigurationForm.js`
- **State/Analytics context**: `AnalyticsContext.js`
- **API client module**: `api.js` (explicit seam between UI and backend)

##### Backend/API service
Evidence: `backend/` directory + frontend has `api.js`.
Split into likely backend modules (confirm by inspecting `backend/`):
- **REST API / Controllers**: endpoints for `/status`, `/logs`, `/anomalies`, `/config`, etc.
- **Data access layer (DAL)**: reads/writes SQLite
- **NIDS orchestration**: either:
1) spawns/controls `nids1.py` / `nids2.py`, or
2) reads outputs written by those scripts (DB/files), or
3) receives events from them (queue/socket)

##### Detection engine (Python runtime)
Evidence: `nids1.py`, `nids2.py`, `requirements.txt`.
Split the “engine” into pipeline stages (these are the core of a NIDS and should be diagrammed distinctly):
- **Packet Capture / Traffic Ingest** (e.g., Scapy sniff on NIC)
- **Preprocessing / Feature Extraction** (Pandas/NumPy style transforms)
- **Signature Detection** (lookup/match against signatures DB)
- **Anomaly Detection / ML Inference** (TensorFlow/PyTorch if actually used)
- **Alert Generation** (severity, metadata)
- **Logging/Reporting Writer** (persist alerts/events)

##### Data stores
Evidence: `nids_signatures.db`, `schema.sql`.
- **Signature DB (SQLite)**: `nids_signatures.db` (known threats)
- **Event/Alert/Logs DB (SQLite)**: implied by `schema.sql` + README logging/reporting

##### Config
README references `config.json` but it’s not in the tree. Treat config as a component anyway:
- **Config file / Settings store** (file-based or DB-based)
- UI Settings page updates it via API

##### Network Interface (NIC)
↓
##### Packet capture (nids1.py / nids2.py)
↓
##### Detection pipeline
- signature matcher → consults **Signature DB**
- anomaly detector → uses **ML model** (if present)
↓
##### Alerts + logs persisted → Logs/Alerts DB
↓
##### Backend API reads DB (or receives events)
↓
##### Frontend SPA fetches via `api.js` and renders
- Dashboard status cards
- Logs list
- Anomalies table

##### User changes thresholds / interface / rules in Settings / ConfigurationForm
↓
##### Frontend calls backend endpoint (e.g., `POST /config`)
↓
##### Backend writes config (file/DB)
↓

##### Real-time aspect (call it out)
- **Polling** from UI to backend (`setInterval` calls to `api.js`)
or
- **Server push** (WebSocket/SSE)
If unknown, put a “?” note and verify in `backend/` + `api.js`.

##### Architectural patterns to highlight (specific to this repo)
- **Pipeline architecture** inside detection engine (capture → preprocess → detect → alert → persist)
- **Separation of concerns**:
- UI components vs `api.js` (API boundary)
- API service vs detection engine (process boundary)
- Signatures vs events/logging (data boundary)
- **Event sourcing-ish logging** (append alerts/logs, then query for dashboard)
- Potential **multi-process** design (engine runs separately from API/UI)

##### Frontend components (inside SPA)
- Pages: Home/Dashboard/Logs/Anomalies/Settings
- Shared: Navbar/Footer/StatusCard
- State: AnalyticsContext
- API client: api.js

##### Detection engine pipeline (inside Python engine)
- Capture
- Feature extraction
- Signature detector
- Anomaly detector
- Alert scorer
- Persistence writer

Example sequence:
Packet arrives → capture → detect → write DB → API query → UI refresh/render.

This resolves ambiguity about timing and ownership.

Elements explicitly:
- **Clear labels**: “REST /logs”, “SQL read”, “SQL write”, “Packet sniff (Scapy)”
- Rectangles: services/containers (SPA, API, Engine)
- Cloud/external: NIC / network traffic, optional external threat intel feeds (if added later)
- **Trust boundaries**:
- Host boundary: what runs on the same machine vs separate machines
- Privilege boundary: packet capture often requires elevated permissions—note that on the engine container

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% A) C4 CONTAINER VIEW
  %% =========================
  subgraph "A) Container View (C4)"
    direction TB

    Analyst["Security Analyst"]:::external
    Browser["Web Browser"]:::external

    subgraph "Host / Deployment Boundary"
      direction TB

      SPA["NIDS Dashboard SPA (React)"]:::frontend
      API["Backend API Service (HTTP)"]:::backend
      Engine["NIDS Detection Engine (Python)"]:::engine

      SigDB[("Signature DB (SQLite)")]:::db
      LogsDB[("Logs & Alerts DB (SQLite)")]:::db

      ConfigStore["Config / Settings Store (File/DB)"]:::config
    end

    NIC["Network Interface / Traffic Source (NIC)"]:::external
  end

  Analyst -->|"uses"| Browser
  Browser -->|"loads SPA assets"| SPA
  SPA -->|"HTTPS REST (status/logs/anomalies/config)"| API
  API <-->|"SQL read/write"| LogsDB
  API -->|"write config"| ConfigStore

  NIC -->|"packet sniff"| Engine
  Engine <-->|"SQL read (signatures)"| SigDB
  Engine -->|"SQL write (events/alerts)"| LogsDB
  Engine -->|"reload config (poll/restart/signal)"| ConfigStore

  RTNote["Real-time monitoring: UI polling or WS/SSE (verify in backend/ + api.js)"]:::note
  SPA -.->|"mechanism"| RTNote

  %% =========================
  %% B) FRONTEND COMPONENTS
  %% =========================
  subgraph "B) Frontend SPA Components"
    direction TB

    subgraph "App Shell"
      direction TB
      AppShell["App Shell / Router"]:::frontend
      Home["Home View"]:::frontend
      Navbar["Navigation Bar"]:::frontend
      Footer["Footer"]:::frontend
    end

    subgraph "Views"
      direction TB
      Dashboard["Dashboard View"]:::frontend
      StatusCard["Status Summary Card"]:::frontend
      Logs["Logs View"]:::frontend
      Anomalies["Anomalies View (Table)"]:::frontend
      Settings["Settings / Configuration View"]:::frontend
      ConfigForm["Configuration Form"]:::frontend
    end

    AnalyticsCtx["State / Analytics Context"]:::frontend
    ApiClient["Frontend API Client"]:::frontend
  end

  AppShell -->|"routes"| Home
  AppShell -->|"routes"| Dashboard
  AppShell -->|"routes"| Logs
  AppShell -->|"routes"| Anomalies
  AppShell -->|"routes"| Settings

  Dashboard -->|"renders"| StatusCard
  Settings -->|"contains"| ConfigForm

  Home -->|"uses state"| AnalyticsCtx
  Dashboard -->|"uses state"| AnalyticsCtx
  Logs -->|"uses state"| AnalyticsCtx
  Anomalies -->|"uses state"| AnalyticsCtx
  Settings -->|"uses state"| AnalyticsCtx

  Home -->|"calls"| ApiClient
  Dashboard -->|"calls"| ApiClient
  Logs -->|"calls"| ApiClient
  Anomalies -->|"calls"| ApiClient
  ConfigForm -->|"POST config"| ApiClient

  ApiClient -->|"HTTP calls"| API

  %% Bridge: container to components
  SPA -.->|"contains"| AppShell
  SPA -.->|"contains"| ApiClient
  SPA -.->|"contains"| AnalyticsCtx
  Navbar -.->|"shared UI"| AppShell
  Footer -.->|"shared UI"| AppShell

  %% =========================
  %% C) DETECTION ENGINE PIPELINE
  %% =========================
  subgraph "C) Detection Engine Pipeline (Python)"
    direction TB

    Capture["Packet Capture / Traffic Ingest"]:::engine
    Preprocess["Preprocessing / Feature Extraction"]:::engine
    SigDetect["Signature-based Detection"]:::engine
    AnomDetect["Anomaly / ML-based Detection"]:::engine
    AlertGen["Alert Generation / Severity"]:::engine
    Persist["Logging / Reporting Writer"]:::engine
  end

  Engine -.->|"implements"| Capture
  Capture -->|"packets"| Preprocess
  Preprocess -->|"features"| SigDetect
  Preprocess -->|"features"| AnomDetect
  SigDetect -->|"matches"| AlertGen
  AnomDetect -->|"scores"| AlertGen
  AlertGen -->|"alerts/events"| Persist
  Persist -->|"SQL write"| LogsDB
  SigDetect <-->|"SQL lookup"| SigDB

  %% =========================
  %% D) RUNTIME DATAFLOW (VERTICAL STORY)
  %% =========================
  subgraph "D) Runtime Dataflow (NIDS → UI) + Control (UI → NIDS)"
    direction TB

    D1["1. Packet arrives at NIC"]:::step
    D2["2. Capture traffic (sniff)"]:::step
    D3["3. Detect (signature + anomaly)"]:::step
    D4["4. Persist alerts/logs"]:::step
    D5["5. API queries logs/anomalies"]:::step
    D6["6. SPA refreshes & renders"]:::step

    C1["Control: User updates Settings"]:::step
    C2["Control: SPA POST /config"]:::step
    C3["Control: API writes config store"]:::step
    C4["Control: Engine reloads config"]:::step
  end

  D1 --> D2 --> D3 --> D4 --> D5 --> D6
  D1 -.->|"source"| NIC
  D2 -.->|"runs in"| Engine
  D3 -.->|"uses"| SigDB
  D4 -.->|"writes"| LogsDB
  D5 -.->|"served by"| API
  D6 -.->|"runs in"| SPA

  C1 --> C2 --> C3 --> C4
  C1 -.->|"UI"| Settings
  C2 -.->|"via"| ApiClient
  C3 -.->|"in"| API
  C4 -.->|"in"| Engine

  %% =========================
  %% CLICK EVENTS (FILES/DIRS)
  %% =========================
  click SPA "https://github.com/bittb/network-intrusion-detection-system/blob/main/App.js"
  click AppShell "https://github.com/bittb/network-intrusion-detection-system/blob/main/App.js"
  click Home "https://github.com/bittb/network-intrusion-detection-system/blob/main/Home.js"
  click Navbar "https://github.com/bittb/network-intrusion-detection-system/blob/main/Navbar.js"
  click Footer "https://github.com/bittb/network-intrusion-detection-system/blob/main/Footer.js"
  click Dashboard "https://github.com/bittb/network-intrusion-detection-system/blob/main/Dashboard.js"
  click StatusCard "https://github.com/bittb/network-intrusion-detection-system/blob/main/StatusCard.js"
  click Logs "https://github.com/bittb/network-intrusion-detection-system/blob/main/Logs.js"
  click Anomalies "https://github.com/bittb/network-intrusion-detection-system/blob/main/AnomaliesTable.js"
  click Settings "https://github.com/bittb/network-intrusion-detection-system/blob/main/Settings.js"
  click ConfigForm "https://github.com/bittb/network-intrusion-detection-system/blob/main/ConfigurationForm.js"
  click AnalyticsCtx "https://github.com/bittb/network-intrusion-detection-system/blob/main/AnalyticsContext.js"
  click ApiClient "https://github.com/bittb/network-intrusion-detection-system/blob/main/api.js"

  click API "https://github.com/bittb/network-intrusion-detection-system/tree/main/backend/"
  click Engine "https://github.com/bittb/network-intrusion-detection-system/blob/main/nids1.py"
  click Capture "https://github.com/bittb/network-intrusion-detection-system/blob/main/nids2.py"

  click SigDB "https://github.com/bittb/network-intrusion-detection-system/blob/main/nids_signatures.db"
  click LogsDB "https://github.com/bittb/network-intrusion-detection-system/blob/main/schema.sql"
  click ConfigStore "https://github.com/bittb/network-intrusion-detection-system/blob/main/schema.sql"
  click RTNote "https://github.com/bittb/network-intrusion-detection-system/blob/main/requirements.txt"

  %% Bonus clicks for additional mapped frontend assets
  click Browser "https://github.com/bittb/network-intrusion-detection-system/blob/main/index.html"
  click Analyst "https://github.com/bittb/network-intrusion-detection-system/blob/main/index.js"
  click D6 "https://github.com/bittb/network-intrusion-detection-system/blob/main/App.css"
  click Home "https://github.com/bittb/network-intrusion-detection-system/blob/main/Home.css"
  click Navbar "https://github.com/bittb/network-intrusion-detection-system/blob/main/Navbar.css"
  click Footer "https://github.com/bittb/network-intrusion-detection-system/blob/main/Footer.css"
  click Dashboard "https://github.com/bittb/network-intrusion-detection-system/blob/main/Dashboard.css"
  click Logs "https://github.com/bittb/network-intrusion-detection-system/blob/main/Logs.css"
  click Anomalies "https://github.com/bittb/network-intrusion-detection-system/blob/main/Anomalies.css"

  %% =========================
  %% STYLES
  %% =========================
  classDef external fill:#E7F0FF,stroke:#2B5DB7,stroke-width:1px,color:#0B1B3A
  classDef frontend fill:#E9FBF1,stroke:#1F7A4D,stroke-width:1px,color:#0F2D1F
  classDef backend fill:#FFF3E6,stroke:#B05A00,stroke-width:1px,color:#3B1E00
  classDef engine fill:#F3E9FF,stroke:#6A2BB7,stroke-width:1px,color:#210B3A
  classDef db fill:#FFF7CC,stroke:#8A6D00,stroke-width:1px,color:#2A2200
  classDef config fill:#FFE6F2,stroke:#B7266A,stroke-width:1px,color:#3A0B22
  classDef note fill:#F5F7FA,stroke:#6B7785,stroke-dasharray: 4 3,stroke-width:1px,color:#111827
  classDef step fill:#FFFFFF,stroke:#4B5563,stroke-width:1px,color:#111827
```
