# nandini905/dpi-engine architecture

> Architecture diagram of the GitHub repository nandini905/dpi-engine, 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/nandini905/dpi-engine
- Repository: https://github.com/nandini905/dpi-engine

## Overview

DPI Engine reads PCAP traffic, parses packets, classifies flows and enforces blocking rules, then writes forwarded packets to an output PCAP. The documented scalable path dispatches packets through load balancers to fast-path workers, with per-worker flow tracking and a queued writer. The graph also includes the available DNS/QUIC extraction capability. Some runtime wiring is unsampled; edges are limited to README statements and shown references/calls.

Main entry points: [`src/dpi_engine.cpp`](https://github.com/nandini905/dpi-engine/blob/main/src/dpi_engine.cpp) (DPI Engine), [`src/fast_path.cpp`](https://github.com/nandini905/dpi-engine/blob/main/src/fast_path.cpp) (Fast Path Workers), [`src/load_balancer.cpp`](https://github.com/nandini905/dpi-engine/blob/main/src/load_balancer.cpp) (Load Balancers), [`include/thread_safe_queue.h`](https://github.com/nandini905/dpi-engine/blob/main/include/thread_safe_queue.h) (Packet Queues)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Capture and Parsing"]
  node_reader["PCAP Reader<br/>[pcap_reader.cpp]"]
  node_parser["Packet Parser<br/>[packet_parser.cpp]"]
end

subgraph group_classification["Classification and Policy"]
  node_extractors["Protocol Extractors<br/>[sni_extractor.cpp]"]
  node_rules["Blocking Rules<br/>[rule_manager.cpp]"]
  node_tracker[("Flow Tracking")]
end

subgraph group_pipeline["Threaded Processing"]
  node_loadbalancer["Load Balancers<br/>[load_balancer.cpp]"]
  node_fastpath["Fast Path Workers<br/>[fast_path.cpp]"]
  node_queues["Packet Queues"]
end

subgraph group_orchestration["Engine and Output"]
  node_engine["DPI Engine<br/>[dpi_engine.cpp]"]
  node_writer["PCAP Output Writer<br/>[dpi_engine.cpp]"]
end

node_user(("Operator"))
node_output["Output PCAP"]

node_user -->|"configures and runs"| node_engine
node_engine -->|"reads input"| node_reader
node_reader -->|"provides packets"| node_parser
node_engine -->|"creates packet jobs"| node_parser
node_engine -->|"dispatches by hash"| node_loadbalancer
node_loadbalancer -->|"dispatches by flow hash"| node_fastpath
node_loadbalancer -->|"passes packets"| node_queues
node_fastpath -->|"receives packets"| node_queues
node_fastpath -->|"tracks flows"| node_tracker
node_fastpath -->|"inspects payload"| node_extractors
node_fastpath -->|"checks policy"| node_rules
node_fastpath -->|"reports packet action"| node_engine
node_engine -->|"queues output"| node_queues
node_engine -->|"handles output"| node_writer
node_writer -->|"writes packets"| node_output
node_user -->|"sets blocking rules"| node_rules

click node_engine "https://github.com/nandini905/dpi-engine/blob/main/src/dpi_engine.cpp"
click node_reader "https://github.com/nandini905/dpi-engine/blob/main/src/pcap_reader.cpp"
click node_parser "https://github.com/nandini905/dpi-engine/blob/main/src/packet_parser.cpp"
click node_extractors "https://github.com/nandini905/dpi-engine/blob/main/src/sni_extractor.cpp"
click node_rules "https://github.com/nandini905/dpi-engine/blob/main/src/rule_manager.cpp"
click node_tracker "https://github.com/nandini905/dpi-engine/blob/main/src/connection_tracker.cpp"
click node_loadbalancer "https://github.com/nandini905/dpi-engine/blob/main/src/load_balancer.cpp"
click node_fastpath "https://github.com/nandini905/dpi-engine/blob/main/src/fast_path.cpp"
click node_queues "https://github.com/nandini905/dpi-engine/blob/main/include/thread_safe_queue.h"
click node_writer "https://github.com/nandini905/dpi-engine/blob/main/src/dpi_engine.cpp"

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_reader,node_parser toneBlue
class node_extractors,node_rules,node_tracker toneAmber
class node_loadbalancer,node_fastpath,node_queues toneMint
class node_engine,node_writer toneRose
class node_user,node_output toneIndigo
```

## Components

### Capture and Parsing

- [PCAP Reader](https://github.com/nandini905/dpi-engine/blob/main/src/pcap_reader.cpp): `src/pcap_reader.cpp`
- [Packet Parser](https://github.com/nandini905/dpi-engine/blob/main/src/packet_parser.cpp): `src/packet_parser.cpp`

### Classification and Policy

- [Protocol Extractors](https://github.com/nandini905/dpi-engine/blob/main/src/sni_extractor.cpp): `src/sni_extractor.cpp`
- [Blocking Rules](https://github.com/nandini905/dpi-engine/blob/main/src/rule_manager.cpp): `src/rule_manager.cpp`
- [Flow Tracking](https://github.com/nandini905/dpi-engine/blob/main/src/connection_tracker.cpp): `src/connection_tracker.cpp`

### Threaded Processing

- [Load Balancers](https://github.com/nandini905/dpi-engine/blob/main/src/load_balancer.cpp): `src/load_balancer.cpp`
- [Fast Path Workers](https://github.com/nandini905/dpi-engine/blob/main/src/fast_path.cpp): `src/fast_path.cpp`
- [Packet Queues](https://github.com/nandini905/dpi-engine/blob/main/include/thread_safe_queue.h): `include/thread_safe_queue.h`

### Engine and Output

- [DPI Engine](https://github.com/nandini905/dpi-engine/blob/main/src/dpi_engine.cpp): `src/dpi_engine.cpp`
- [PCAP Output Writer](https://github.com/nandini905/dpi-engine/blob/main/src/dpi_engine.cpp): `src/dpi_engine.cpp`

### Other components

- **Operator**
- **Output PCAP**

## Connections

- Operator → DPI Engine: configures and runs (evidence: `README.md`)
- DPI Engine → PCAP Reader: reads input (evidence: `README.md`)
- PCAP Reader → Packet Parser: provides packets (evidence: `README.md`)
- DPI Engine → Packet Parser: creates packet jobs (evidence: `src/dpi_engine.cpp`)
- DPI Engine → Load Balancers: dispatches by hash (evidence: `README.md`)
- Load Balancers → Fast Path Workers: dispatches by flow hash (evidence: `README.md`)
- Load Balancers → Packet Queues: passes packets
- Fast Path Workers → Packet Queues: receives packets
- Fast Path Workers → Flow Tracking: tracks flows
- Fast Path Workers → Protocol Extractors: inspects payload
- Fast Path Workers → Blocking Rules: checks policy
- Fast Path Workers → DPI Engine: reports packet action
- DPI Engine → Packet Queues: queues output (evidence: `src/dpi_engine.cpp`)
- DPI Engine → PCAP Output Writer: handles output (evidence: `src/dpi_engine.cpp`)
- PCAP Output Writer → Output PCAP: writes packets (evidence: `README.md`)
- Operator → Blocking Rules: sets blocking rules (evidence: `README.md`)
