# xvzc/spoofdpi architecture

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

- Interactive diagram: https://gitdiagram.com/xvzc/spoofdpi
- Repository: https://github.com/xvzc/spoofdpi

## Overview

SpoofDPI is a Go proxy for countering DPI-based censorship. Its main workflow is to load CLI/configuration, start a selected proxy mode, accept client traffic, and forward it while applying TLS or UDP desynchronization where configured. HTTP, SOCKS5, and TUN modes have distinct handlers; DNS resolution, rules, packet-based hop learning, and connection utilities support those paths. The source index documents imports and module references, but several server constructors and runtime modules were not excerpted, so those links are limited to relationships visible in the index or README.

Main entry points: [`cmd/spoofdpi/main.go`](https://github.com/xvzc/spoofdpi/blob/main/cmd/spoofdpi/main.go) (Application startup), [`internal/netutil/conn.go`](https://github.com/xvzc/spoofdpi/blob/main/internal/netutil/conn.go) (Connection utilities), [`internal/desync/tls.go`](https://github.com/xvzc/spoofdpi/blob/main/internal/desync/tls.go) (TLS desynchronizer), [`internal/server/socks5/socks5.go`](https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/socks5.go) (SOCKS5 proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and configuration"]
  node_app["Application startup<br/>[main.go]"]
  node_tui["Terminal UI<br/>[tui.go]"]
  node_config["Config and CLI<br/>[cli.go]"]
end

subgraph group_proxy["Proxy modes"]
  node_httpserver["HTTP proxy<br/>[http.go]"]
  node_httphandler["HTTP request handler<br/>[handler_http.go]"]
  node_httpshandler["HTTPS handler<br/>[handler_https.go]"]
  node_socksserver["SOCKS5 proxy<br/>[socks5.go]"]
  node_socksconnect["SOCKS5 connect<br/>[handler_connect.go]"]
  node_socksbind["SOCKS5 bind<br/>[handler_bind.go]"]
  node_socksudp["SOCKS5 UDP associate"]
  node_tunserver["TUN server<br/>[tun.go]"]
  node_tuntcp["TUN TCP handler<br/>[handler_tcp.go]"]
  node_tunudp["TUN UDP handler<br/>[handler_udp.go]"]
end

subgraph group_bypass["DPI circumvention"]
  node_tls["TLS desynchronizer<br/>[tls.go]"]
  node_udpdesync["UDP desynchronizer<br/>[udp.go]"]
  node_packets["Packet capture and writers"]
end

subgraph group_support["Network support"]
  node_rules["Rule matching<br/>[set.go]"]
  node_dns["DNS resolution<br/>[client.go]"]
  node_cache["Caches<br/>[cache.go]"]
  node_netutil["Connection utilities<br/>[conn.go]"]
  node_protocol["Protocol parsing<br/>[tls.go]"]
  node_session["Session context<br/>[session.go]"]
end

node_user(("CLI user"))

node_user -->|"starts"| node_app
node_app -->|"creates command"| node_config
node_app -->|"creates trace context"| node_session
node_app -->|"starts selected mode"| node_httpserver
node_app -->|"starts selected mode"| node_socksserver
node_app -->|"starts selected mode"| node_tunserver
node_app -->|"initializes resolver"| node_dns
node_app -->|"builds rule set"| node_rules
node_app -->|"starts capture"| node_packets
node_app -->|"constructs desyncer"| node_tls
node_app -->|"constructs desyncer"| node_udpdesync
node_httpserver -.->|"dispatches requests"| node_httphandler
node_httpserver -.->|"dispatches tunnels"| node_httpshandler
node_httpshandler -->|"desynchronizes hello"| node_tls
node_httpshandler -->|"dials and tunnels"| node_netutil
node_httphandler -->|"dials and tunnels"| node_netutil
node_socksserver -.->|"dispatches requests"| node_socksconnect
node_socksserver -.->|"dispatches requests"| node_socksbind
node_socksserver -.->|"dispatches requests"| node_socksudp
node_socksudp -->|"tracks UDP hops"| node_udpdesync
node_socksudp -->|"dials and pools"| node_netutil
node_socksconnect -->|"desynchronizes TLS"| node_tls
node_socksbind -->|"tunnels connections"| node_netutil
node_tunserver -.->|"dispatches TCP"| node_tuntcp
node_tunserver -.->|"dispatches UDP"| node_tunudp
node_tuntcp -->|"matches destinations"| node_rules
node_tuntcp -->|"desynchronizes hello"| node_tls
node_tuntcp -->|"dials and tunnels"| node_netutil
node_tunudp -->|"matches destinations"| node_rules
node_tunudp -->|"desynchronizes traffic"| node_udpdesync
node_tunudp -->|"dials and tunnels"| node_netutil
node_tls -->|"sends crafted packets"| node_packets
node_tls -->|"splits TLS messages"| node_protocol
node_dns -->|"caches answers"| node_cache
node_tui -->|"uses network helpers"| node_netutil

click node_app "https://github.com/xvzc/spoofdpi/blob/main/cmd/spoofdpi/main.go"
click node_tui "https://github.com/xvzc/spoofdpi/blob/main/cmd/spoofdpi/tui.go"
click node_config "https://github.com/xvzc/spoofdpi/blob/main/internal/config/cli.go"
click node_httpserver "https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/http.go"
click node_httphandler "https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/handler_http.go"
click node_httpshandler "https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/handler_https.go"
click node_socksserver "https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/socks5.go"
click node_socksconnect "https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_connect.go"
click node_socksbind "https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_bind.go"
click node_socksudp "https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_udp_assoc.go"
click node_tunserver "https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/tun.go"
click node_tuntcp "https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/handler_tcp.go"
click node_tunudp "https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/handler_udp.go"
click node_tls "https://github.com/xvzc/spoofdpi/blob/main/internal/desync/tls.go"
click node_udpdesync "https://github.com/xvzc/spoofdpi/blob/main/internal/desync/udp.go"
click node_packets "https://github.com/xvzc/spoofdpi/tree/main/internal/packet"
click node_rules "https://github.com/xvzc/spoofdpi/blob/main/internal/rule/set.go"
click node_dns "https://github.com/xvzc/spoofdpi/blob/main/internal/dns/client.go"
click node_cache "https://github.com/xvzc/spoofdpi/blob/main/internal/cache/cache.go"
click node_netutil "https://github.com/xvzc/spoofdpi/blob/main/internal/netutil/conn.go"
click node_protocol "https://github.com/xvzc/spoofdpi/blob/main/internal/proto/tls.go"
click node_session "https://github.com/xvzc/spoofdpi/blob/main/internal/session/session.go"

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_app,node_tui,node_config,node_user toneBlue
class node_httpserver,node_httphandler,node_httpshandler,node_socksserver,node_socksconnect,node_socksbind,node_socksudp,node_tunserver,node_tuntcp,node_tunudp toneAmber
class node_tls,node_udpdesync,node_packets toneMint
class node_rules,node_dns,node_cache,node_netutil,node_protocol,node_session toneRose
```

## Components

### Startup and configuration

- [Application startup](https://github.com/xvzc/spoofdpi/blob/main/cmd/spoofdpi/main.go): `cmd/spoofdpi/main.go`
- [Terminal UI](https://github.com/xvzc/spoofdpi/blob/main/cmd/spoofdpi/tui.go): `cmd/spoofdpi/tui.go`
- [Config and CLI](https://github.com/xvzc/spoofdpi/blob/main/internal/config/cli.go): `internal/config/cli.go`

### Proxy modes

- [HTTP proxy](https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/http.go): `internal/server/http/http.go`
- [HTTP request handler](https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/handler_http.go): `internal/server/http/handler_http.go`
- [HTTPS handler](https://github.com/xvzc/spoofdpi/blob/main/internal/server/http/handler_https.go): `internal/server/http/handler_https.go`
- [SOCKS5 proxy](https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/socks5.go): `internal/server/socks5/socks5.go`
- [SOCKS5 connect](https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_connect.go): `internal/server/socks5/handler_connect.go`
- [SOCKS5 bind](https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_bind.go): `internal/server/socks5/handler_bind.go`
- [SOCKS5 UDP associate](https://github.com/xvzc/spoofdpi/blob/main/internal/server/socks5/handler_udp_assoc.go): `internal/server/socks5/handler_udp_assoc.go`
- [TUN server](https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/tun.go): `internal/server/tun/tun.go`
- [TUN TCP handler](https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/handler_tcp.go): `internal/server/tun/handler_tcp.go`
- [TUN UDP handler](https://github.com/xvzc/spoofdpi/blob/main/internal/server/tun/handler_udp.go): `internal/server/tun/handler_udp.go`

### DPI circumvention

- [TLS desynchronizer](https://github.com/xvzc/spoofdpi/blob/main/internal/desync/tls.go): `internal/desync/tls.go`
- [UDP desynchronizer](https://github.com/xvzc/spoofdpi/blob/main/internal/desync/udp.go): `internal/desync/udp.go`
- [Packet capture and writers](https://github.com/xvzc/spoofdpi/tree/main/internal/packet): `internal/packet`

### Network support

- [Rule matching](https://github.com/xvzc/spoofdpi/blob/main/internal/rule/set.go): `internal/rule/set.go`
- [DNS resolution](https://github.com/xvzc/spoofdpi/blob/main/internal/dns/client.go): `internal/dns/client.go`
- [Caches](https://github.com/xvzc/spoofdpi/blob/main/internal/cache/cache.go): `internal/cache/cache.go`
- [Connection utilities](https://github.com/xvzc/spoofdpi/blob/main/internal/netutil/conn.go): `internal/netutil/conn.go`
- [Protocol parsing](https://github.com/xvzc/spoofdpi/blob/main/internal/proto/tls.go): `internal/proto/tls.go`
- [Session context](https://github.com/xvzc/spoofdpi/blob/main/internal/session/session.go): `internal/session/session.go`

### Other components

- **CLI user**

## Connections

- CLI user → Application startup: starts (evidence: `cmd/spoofdpi/main.go`)
- Application startup → Config and CLI: creates command (evidence: `cmd/spoofdpi/main.go`)
- Application startup → Session context: creates trace context (evidence: `cmd/spoofdpi/main.go`)
- Application startup → HTTP proxy: starts selected mode (evidence: `cmd/spoofdpi/main.go`)
- Application startup → SOCKS5 proxy: starts selected mode (evidence: `cmd/spoofdpi/main.go`)
- Application startup → TUN server: starts selected mode (evidence: `cmd/spoofdpi/main.go`)
- Application startup → DNS resolution: initializes resolver (evidence: `cmd/spoofdpi/main.go`)
- Application startup → Rule matching: builds rule set (evidence: `cmd/spoofdpi/main.go`)
- Application startup → Packet capture and writers: starts capture (evidence: `cmd/spoofdpi/main.go`)
- Application startup → TLS desynchronizer: constructs desyncer (evidence: `cmd/spoofdpi/main.go`)
- Application startup → UDP desynchronizer: constructs desyncer (evidence: `cmd/spoofdpi/main.go`)
- HTTP proxy → HTTP request handler: dispatches requests
- HTTP proxy → HTTPS handler: dispatches tunnels
- HTTPS handler → TLS desynchronizer: desynchronizes hello (evidence: `internal/server/http/handler_https.go`)
- HTTPS handler → Connection utilities: dials and tunnels (evidence: `internal/server/http/handler_https.go`)
- HTTP request handler → Connection utilities: dials and tunnels (evidence: `internal/server/http/handler_http.go`)
- SOCKS5 proxy → SOCKS5 connect: dispatches requests
- SOCKS5 proxy → SOCKS5 bind: dispatches requests
- SOCKS5 proxy → SOCKS5 UDP associate: dispatches requests
- SOCKS5 UDP associate → UDP desynchronizer: tracks UDP hops (evidence: `internal/server/socks5/handler_udp_assoc.go`)
- SOCKS5 UDP associate → Connection utilities: dials and pools (evidence: `internal/server/socks5/handler_udp_assoc.go`)
- SOCKS5 connect → TLS desynchronizer: desynchronizes TLS (evidence: `internal/server/socks5/handler_connect.go`)
- SOCKS5 bind → Connection utilities: tunnels connections (evidence: `internal/server/socks5/handler_bind.go`)
- TUN server → TUN TCP handler: dispatches TCP
- TUN server → TUN UDP handler: dispatches UDP
- TUN TCP handler → Rule matching: matches destinations (evidence: `internal/server/tun/handler_tcp.go`)
- TUN TCP handler → TLS desynchronizer: desynchronizes hello (evidence: `internal/server/tun/handler_tcp.go`)
- TUN TCP handler → Connection utilities: dials and tunnels (evidence: `internal/server/tun/handler_tcp.go`)
- TUN UDP handler → Rule matching: matches destinations (evidence: `internal/server/tun/handler_udp.go`)
- TUN UDP handler → UDP desynchronizer: desynchronizes traffic (evidence: `internal/server/tun/handler_udp.go`)
- TUN UDP handler → Connection utilities: dials and tunnels (evidence: `internal/server/tun/handler_udp.go`)
- TLS desynchronizer → Packet capture and writers: sends crafted packets (evidence: `internal/desync/tls.go`)
- TLS desynchronizer → Protocol parsing: splits TLS messages (evidence: `internal/desync/tls.go`)
- DNS resolution → Caches: caches answers (evidence: `internal/dns/client.go`)
- Terminal UI → Connection utilities: uses network helpers (evidence: `cmd/spoofdpi/tui.go`)
