# snehify/packetdetective architecture

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

- Interactive diagram: https://gitdiagram.com/snehify/packetdetective
- Repository: https://github.com/snehify/packetdetective

## Overview

This Java packet-inspection application reads classic PCAP files, parses packets, distributes IP traffic across worker threads, classifies connections using payload clues, applies blocking rules, and writes forwarded packets to a new PCAP. It also provides a packet-summary command. The principal flow is visible in the DPI engine and worker excerpts; alternate entry points and other capabilities are represented only where the source index or excerpts establish them.

Main entry points: [`external/dcpappi/include/DPIEngine.java`](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/DPIEngine.java) (DPI engine), [`external/dcpappi/include/FastPathProcessor.java`](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/FastPathProcessor.java) (Fast-path workers), [`external/dcpappi/src/MainPacketSummary.java`](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/src/MainPacketSummary.java) (Packet summary), [`external/dcpappi/include/PacketParser.java`](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/PacketParser.java) (Packet parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command entry points"]
  node_main["DPI command<br/>[Main.java]"]
  node_summary["Packet summary"]
end

subgraph group_capture["PCAP processing"]
  node_engine["DPI engine<br/>[DPIEngine.java]"]
  node_pcap["PCAP reader<br/>[PcapReader.java]"]
  node_parser["Packet parser<br/>[PacketParser.java]"]
  node_output["Output PCAP"]
end

subgraph group_workers["Parallel inspection"]
  node_loadbalancer["Load balancer<br/>[LoadBalancer.java]"]
  node_fastpath["Fast-path workers"]
end

subgraph group_classification["Classification and policy"]
  node_connection[("Connection tracker")]
  node_sni["Payload classification<br/>[SNIExtractor.java]"]
  node_rules["Blocking rules<br/>[RuleManager.java]"]
end

subgraph group_internals["Shared runtime"]
  node_queues["Work queues"]
  node_types["Packet and flow types<br/>[Types.java]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_main
node_operator -->|"runs"| node_summary
node_main -->|"initializes and processes"| node_engine
node_summary -->|"reads packets"| node_pcap
node_summary -->|"parses packets"| node_parser
node_engine -->|"reads input"| node_pcap
node_engine -->|"parses packets"| node_parser
node_engine -->|"dispatches jobs"| node_loadbalancer
node_engine -->|"starts and stops"| node_fastpath
node_engine -->|"loads rules"| node_rules
node_engine -->|"queues output"| node_queues
node_engine -->|"writes forwarded packets"| node_output
node_loadbalancer -->|"dispatches jobs"| node_queues
node_fastpath -->|"consumes jobs"| node_queues
node_fastpath -->|"tracks flows"| node_connection
node_fastpath -->|"extracts host clues"| node_sni
node_fastpath -->|"checks policy"| node_rules
node_parser -->|"creates packet jobs"| node_types
node_connection -->|"stores connection state"| node_types
node_rules -->|"uses app types"| node_types

click node_main "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/src/Main.java"
click node_summary "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/src/MainPacketSummary.java"
click node_engine "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/DPIEngine.java"
click node_pcap "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/PcapReader.java"
click node_parser "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/PacketParser.java"
click node_loadbalancer "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/LoadBalancer.java"
click node_fastpath "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/FastPathProcessor.java"
click node_queues "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/ThreadSafeQueue.java"
click node_connection "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/ConnectionTracker.java"
click node_sni "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/SNIExtractor.java"
click node_rules "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/RuleManager.java"
click node_types "https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/Types.java"

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_main,node_summary toneBlue
class node_engine,node_pcap,node_parser,node_output toneAmber
class node_loadbalancer,node_fastpath toneMint
class node_connection,node_sni,node_rules toneRose
class node_queues,node_types,node_operator toneIndigo
```

## Components

### Command entry points

- [DPI command](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/src/Main.java): `external/dcpappi/src/Main.java`
- [Packet summary](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/src/MainPacketSummary.java): `external/dcpappi/src/MainPacketSummary.java`

### PCAP processing

- [DPI engine](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/DPIEngine.java): `external/dcpappi/include/DPIEngine.java`
- [PCAP reader](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/PcapReader.java): `external/dcpappi/include/PcapReader.java`
- [Packet parser](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/PacketParser.java): `external/dcpappi/include/PacketParser.java`
- **Output PCAP**

### Parallel inspection

- [Load balancer](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/LoadBalancer.java): `external/dcpappi/include/LoadBalancer.java`
- [Fast-path workers](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/FastPathProcessor.java): `external/dcpappi/include/FastPathProcessor.java`

### Classification and policy

- [Connection tracker](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/ConnectionTracker.java): `external/dcpappi/include/ConnectionTracker.java`
- [Payload classification](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/SNIExtractor.java): `external/dcpappi/include/SNIExtractor.java`
- [Blocking rules](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/RuleManager.java): `external/dcpappi/include/RuleManager.java`

### Shared runtime

- [Work queues](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/ThreadSafeQueue.java): `external/dcpappi/include/ThreadSafeQueue.java`
- [Packet and flow types](https://github.com/snehify/packetdetective/blob/main/external/dcpappi/include/Types.java): `external/dcpappi/include/Types.java`

### Other components

- **Operator**

## Connections

- Operator → DPI command: runs (evidence: `external/dcpappi/src/Main.java`)
- Operator → Packet summary: runs (evidence: `external/dcpappi/src/MainPacketSummary.java`)
- DPI command → DPI engine: initializes and processes (evidence: `external/dcpappi/src/Main.java`)
- Packet summary → PCAP reader: reads packets (evidence: `external/dcpappi/src/MainPacketSummary.java`)
- Packet summary → Packet parser: parses packets (evidence: `external/dcpappi/src/MainPacketSummary.java`)
- DPI engine → PCAP reader: reads input (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Packet parser: parses packets (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Load balancer: dispatches jobs (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Fast-path workers: starts and stops (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Blocking rules: loads rules (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Work queues: queues output (evidence: `external/dcpappi/include/DPIEngine.java`)
- DPI engine → Output PCAP: writes forwarded packets (evidence: `external/dcpappi/include/DPIEngine.java`)
- Load balancer → Work queues: dispatches jobs (evidence: `external/dcpappi/include/LoadBalancer.java`)
- Fast-path workers → Work queues: consumes jobs (evidence: `external/dcpappi/include/FastPathProcessor.java`)
- Fast-path workers → Connection tracker: tracks flows (evidence: `external/dcpappi/include/FastPathProcessor.java`)
- Fast-path workers → Payload classification: extracts host clues (evidence: `external/dcpappi/include/FastPathProcessor.java`)
- Fast-path workers → Blocking rules: checks policy (evidence: `external/dcpappi/include/FastPathProcessor.java`)
- Packet parser → Packet and flow types: creates packet jobs (evidence: `external/dcpappi/include/PacketParser.java`)
- Connection tracker → Packet and flow types: stores connection state (evidence: `external/dcpappi/include/ConnectionTracker.java`)
- Blocking rules → Packet and flow types: uses app types (evidence: `external/dcpappi/include/RuleManager.java`)