# shashank17singh/dpi-engine architecture

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

- Interactive diagram: https://gitdiagram.com/shashank17singh/dpi-engine
- Repository: https://github.com/shashank17singh/dpi-engine

## Overview

DPI Engine is a C++ PCAP analyzer that parses packets, tracks 5-tuple flows, classifies traffic using TLS SNI and HTTP Host data, applies configurable firewall rules, and writes a filtered capture. The principal workflow is documented as PCAP reader → load balancers → fast paths → classification/rules → output writer. Internal parsing, flow state, classification, and concurrency stages are represented separately. The README documents the threaded architecture; sampled source confirms parser, rule, and extractor responsibilities, but excerpts do not expose every runtime call or queue handoff.

Main entry points: [`src/dpi_mt.cpp`](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp) (Fast Paths), [`src/packet_parser.cpp`](https://github.com/shashank17singh/dpi-engine/blob/main/src/packet_parser.cpp) (Packet Parser), [`src/pcap_reader.cpp`](https://github.com/shashank17singh/dpi-engine/blob/main/src/pcap_reader.cpp) (PCAP Reader), [`src/main_working.cpp`](https://github.com/shashank17singh/dpi-engine/blob/main/src/main_working.cpp) (Single-thread Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Capture Ingestion"]
  node_cli["Engine CLI<br/>[dpi_mt.cpp]"]
  node_reader["PCAP Reader<br/>[pcap_reader.cpp]"]
  node_writer["Output Writer<br/>[dpi_mt.cpp]"]
  node_simple["Single-thread Engine<br/>[main_working.cpp]"]
end

subgraph group_inspect["Packet Inspection"]
  node_parsed["Packet Parser<br/>[packet_parser.cpp]"]
  node_platform["Byte Order<br/>[platform.h]"]
  node_flow["Flow State<br/>[types.h]"]
  node_extractors["Protocol Extractors<br/>[sni_extractor.cpp]"]
end

subgraph group_policy["Classification Policy"]
  node_classify["App Classification<br/>[types.cpp]"]
  node_rules["Firewall Rules<br/>[dpi_mt.cpp]"]
end

subgraph group_parallel["Parallel Processing"]
  node_loadbalancer["Load Balancers<br/>[dpi_mt.cpp]"]
  node_fastpath["Fast Paths<br/>[dpi_mt.cpp]"]
  node_queues["Thread Queues<br/>[dpi_mt.cpp]"]
end

node_operator(("Operator"))
node_input["Input PCAP"]
node_output["Filtered PCAP"]

node_operator -->|"configures"| node_cli
node_input -->|"reads packets"| node_reader
node_cli -->|"processes capture"| node_reader
node_reader -->|"parses packets"| node_parsed
node_parsed -->|"converts byte order"| node_platform
node_parsed -.->|"builds flow tuple"| node_flow
node_fastpath -->|"inspects payload"| node_extractors
node_fastpath -.->|"maps domain"| node_classify
node_cli -->|"configures rules"| node_rules
node_loadbalancer -->|"dispatches flows"| node_fastpath
node_cli -->|"distributes packets"| node_loadbalancer
node_loadbalancer -.->|"enqueues packets"| node_queues
node_queues -.->|"delivers packets"| node_fastpath
node_fastpath -.->|"checks policy"| node_rules
node_fastpath -->|"forwards allowed packets"| node_writer
node_writer -->|"writes capture"| node_output
node_operator -->|"runs reference engine"| node_simple
node_simple -.->|"reads capture"| node_input

click node_cli "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_reader "https://github.com/shashank17singh/dpi-engine/blob/main/src/pcap_reader.cpp"
click node_parsed "https://github.com/shashank17singh/dpi-engine/blob/main/src/packet_parser.cpp"
click node_platform "https://github.com/shashank17singh/dpi-engine/blob/main/include/platform.h"
click node_flow "https://github.com/shashank17singh/dpi-engine/blob/main/include/types.h"
click node_extractors "https://github.com/shashank17singh/dpi-engine/blob/main/src/sni_extractor.cpp"
click node_classify "https://github.com/shashank17singh/dpi-engine/blob/main/src/types.cpp"
click node_rules "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_loadbalancer "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_fastpath "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_queues "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_writer "https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp"
click node_simple "https://github.com/shashank17singh/dpi-engine/blob/main/src/main_working.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_cli,node_reader,node_writer,node_simple toneBlue
class node_parsed,node_platform,node_flow,node_extractors toneAmber
class node_classify,node_rules toneMint
class node_loadbalancer,node_fastpath,node_queues toneRose
class node_operator,node_input,node_output toneIndigo
```

## Components

### Capture Ingestion

- [Engine CLI](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`
- [PCAP Reader](https://github.com/shashank17singh/dpi-engine/blob/main/src/pcap_reader.cpp): `src/pcap_reader.cpp`
- [Output Writer](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`
- [Single-thread Engine](https://github.com/shashank17singh/dpi-engine/blob/main/src/main_working.cpp): `src/main_working.cpp`

### Packet Inspection

- [Packet Parser](https://github.com/shashank17singh/dpi-engine/blob/main/src/packet_parser.cpp): `src/packet_parser.cpp`
- [Byte Order](https://github.com/shashank17singh/dpi-engine/blob/main/include/platform.h): `include/platform.h`
- [Flow State](https://github.com/shashank17singh/dpi-engine/blob/main/include/types.h): `include/types.h`
- [Protocol Extractors](https://github.com/shashank17singh/dpi-engine/blob/main/src/sni_extractor.cpp): `src/sni_extractor.cpp`

### Classification Policy

- [App Classification](https://github.com/shashank17singh/dpi-engine/blob/main/src/types.cpp): `src/types.cpp`
- [Firewall Rules](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`

### Parallel Processing

- [Load Balancers](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`
- [Fast Paths](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`
- [Thread Queues](https://github.com/shashank17singh/dpi-engine/blob/main/src/dpi_mt.cpp): `src/dpi_mt.cpp`

### Other components

- **Operator**
- **Input PCAP**
- **Filtered PCAP**

## Connections

- Operator → Engine CLI: configures (evidence: `README.md`)
- Input PCAP → PCAP Reader: reads packets (evidence: `README.md`)
- Engine CLI → PCAP Reader: processes capture (evidence: `src/dpi_mt.cpp`)
- PCAP Reader → Packet Parser: parses packets (evidence: `README.md`)
- Packet Parser → Byte Order: converts byte order (evidence: `src/packet_parser.cpp`)
- Packet Parser → Flow State: builds flow tuple
- Fast Paths → Protocol Extractors: inspects payload (evidence: `src/dpi_mt.cpp`)
- Fast Paths → App Classification: maps domain
- Engine CLI → Firewall Rules: configures rules (evidence: `src/dpi_mt.cpp`)
- Load Balancers → Fast Paths: dispatches flows (evidence: `README.md`)
- Engine CLI → Load Balancers: distributes packets (evidence: `README.md`)
- Load Balancers → Thread Queues: enqueues packets (evidence: `src/dpi_mt.cpp`)
- Thread Queues → Fast Paths: delivers packets (evidence: `src/dpi_mt.cpp`)
- Fast Paths → Firewall Rules: checks policy (evidence: `src/dpi_mt.cpp`)
- Fast Paths → Output Writer: forwards allowed packets (evidence: `README.md`)
- Output Writer → Filtered PCAP: writes capture (evidence: `README.md`)
- Operator → Single-thread Engine: runs reference engine (evidence: `README.md`)
- Single-thread Engine → Input PCAP: reads capture
