# gvcoder09/nodpi architecture

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

- Interactive diagram: https://gitdiagram.com/gvcoder09/nodpi
- Repository: https://github.com/gvcoder09/nodpi

## Overview

##### Project type and purpose
- NoDPI is a cross-platform, command-line HTTP(S) proxy tool written in Python (standard library only).
- Purpose: intercept and fragment TLS ClientHello packets according to configurable methods to bypass Deep Packet Inspection (DPI).

##### File structure
- Top-level artifacts:
- Dockerfile – defines a container image for running the proxy.
- nodpi.spec – PyInstaller spec for building a standalone executable.
- big-blacklist.txt / blacklist.txt – default domain filters.
- src/main.py – single-point entry-point with all logic.
- CI/CD: .github/workflows/codeql.yml.

##### Extract key architectural insights from the README
- Workflow: CLI → load config/blacklist → launch proxy → intercept traffic → apply fragmentation logic → forward to target → log events.
- Two fragmentation algorithms: Random and SNI-based.
- Optional autoblacklist (dynamic detection of blocked domains).
- Supports Docker, native Python run, PyInstaller build, and autostart integration on Windows/Linux.

a. CLI / Argument Parser
b. Configuration & Blacklist Manager
c. Proxy Server (TCP listener)
d. Connection Handler
e. TLS ClientHello Fragmenter
f. Outgoing Connector (to target HTTPS server)
g. Logging Subsystem (access & error logs)
h. Deployment Artifacts (PyInstaller build, Docker container)

##### Relationships & data flows
- User issues `nodpi` command → CLI parses args → config & blacklist loaded → ProxyServer starts listening on HOST:PORT.
- Browser / system HTTP(S) proxy → connects to ProxyServer.
- ConnectionHandler reads ClientHello → passes through Fragmenter (Random or SNI) → hands off patched packet to OutgoingConnector → real server.
- Responses flow back unmodified.
- BlacklistManager consulted on each hostname; autoblacklist toggles interception.
- All events funnel into Logger.

##### Architectural patterns & design principles
- Modular separation (even if all in `main.py`, conceptually split):
- Input (CLI) vs Core Logic (network, fragmentation) vs Output (network, logs).
- Strategy pattern for fragmentation methods.
- Single responsibility for Blacklist and Logging.
- Cross-platform abstraction (pure Python, no native deps).
- Deployment pipelines: containerization and packaging via PyInstaller.

##### Technologies / frameworks
- Python 3.9+ standard library (socketserver, ssl, argparse, logging, etc.)
- PyInstaller (via `nodpi.spec`)
- Docker (via `Dockerfile`)
- OS integration (autostart through registry or `~/.config/autostart`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        CLIParser["CLI / Argument Parser"]:::config
        BlacklistManager["Configuration & Blacklist Manager"]:::config
        StaticBL1["big-blacklist.txt"]:::config
        StaticBL2["blacklist.txt"]:::config
    end

    %% Core Proxy Pipeline
    subgraph "Core Proxy Pipeline"
        ProxyServer["Proxy Server\n(TCP listener)"]:::network
        ConnectionHandler["Connection Handler"]:::network
        Fragmenter["TLS ClientHello Fragmenter\n(Random & SNI)"]:::processing
        OutgoingConnector["Outgoing Connector\n(to target HTTPS)"]:::network
    end

    %% Logging Subsystem
    subgraph "Logging Subsystem"
        Logger["Logging Subsystem\n(access & error logs)"]:::deployment
    end

    %% Deployment Artifacts
    subgraph "Deployment Artifacts"
        Docker["Docker Container"]:::deployment
        PyInstaller["PyInstaller Build"]:::deployment
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CICD["CodeQL Scanning"]:::cicd
    end

    %% Documentation & Assets
    subgraph "Documentation & Assets"
        Assets["Assets\n(icons & screenshots)"]:::deployment
    end

    %% External Entities
    Browser["Browser / System"]:::external
    TargetServer["Target HTTPS Server"]:::external

    %% Data Flows
    Browser -->|HTTPS over TCP:8881| ProxyServer
    CLIParser -->|loads config| BlacklistManager
    StaticBL1 --> BlacklistManager
    StaticBL2 --> BlacklistManager
    BlacklistManager -->|provides blacklist| ProxyServer
    ProxyServer -->|new connection| ConnectionHandler
    ConnectionHandler -->|reads ClientHello| Fragmenter
    Fragmenter -->|sends patched packet| OutgoingConnector
    OutgoingConnector -->|connects to| TargetServer
    TargetServer -->|response| Browser
    ConnectionHandler -->|logs event| Logger

    %% Click Events
    click CLIParser "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click BlacklistManager "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click StaticBL1 "https://github.com/gvcoder09/nodpi/blob/main/big-blacklist.txt"
    click StaticBL2 "https://github.com/gvcoder09/nodpi/blob/main/blacklist.txt"
    click ProxyServer "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click ConnectionHandler "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click Fragmenter "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click OutgoingConnector "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click Logger "https://github.com/gvcoder09/nodpi/blob/main/src/main.py"
    click Docker "https://github.com/gvcoder09/nodpi/tree/main/Dockerfile"
    click PyInstaller "https://github.com/gvcoder09/nodpi/blob/main/nodpi.spec"
    click CICD "https://github.com/gvcoder09/nodpi/blob/main/.github/workflows/codeql.yml"
    click Assets "https://github.com/gvcoder09/nodpi/tree/main/assets/"

    %% Styles
    classDef network fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef config fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef processing fill:#ffe0b2,stroke:#f57c00,color:#e65100;
    classDef deployment fill:#e0e0e0,stroke:#616161,color:#212121;
    classDef cicd fill:#d1c4e9,stroke:#7e57c2,color:#4a148c;
    classDef external fill:#ffffff,stroke:#9e9e9e,color:#424242;
```
