# cuishuang/shadowsocks architecture

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

- Interactive diagram: https://gitdiagram.com/cuishuang/shadowsocks
- Repository: https://github.com/cuishuang/shadowsocks

## Overview

##### Project type and purpose
- This is a Golang-based tunnel-proxy tool (an implementation and walkthrough of “go-shadowsocks2”). It provides a command-line client/server that sets up encrypted TCP/UDP tunnels (Shadowsocks).
- The README confirms it’s a tutorial-style deep dive into how Shadowsocks implements a tunnel proxy.

##### File structure
Top-level:
- main.go                    — entry point for the CLI tool
- configure.go / configure_test.go — code to load and validate JSON configs
- conf/client.json, conf/server.json — example client/server configurations
- core/                      — core abstractions: cipher, packet, stream
- shadowaead/                — AEAD cipher implementations
- socks/                     — SOCKS5 address parsing and protocol helpers
- nfutil/, pfutil/           — platform-specific OS-integration (netfilter for Linux, PF for Darwin)
- plugin.go                  — plugin hooks (e.g., obfs, traffic‐shaping)
- tcp.go, udp.go             — local/remote tunnel logic and relay
- demo/                      — sample gateway & tunnel deployments
- Dockerfile, Makefile       — containerization and build scripts
- .github/workflows/*.yml    — CI/CD pipelines for build & release

##### README for additional insights
- It outlines the tunnel proxy flow, key functions (tcpLocal, tcpRemote, relay), and major code concepts (io.Copy for stream forwarding, ReadAddr/Write for target IP encapsulation, goroutines + WaitGroup to avoid blocking).

##### Key takeaways
– Be exhaustive: represent each directory/package as a distinct component if it has unique responsibilities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Main["main.go"]:::app
        ConfigLoad["configure.go"]:::app
        ConfigTest["configure_test.go"]:::app
        ClientConf["conf/client.json"]:::app
        ServerConf["conf/server.json"]:::app
    end

    %% Core Library
    subgraph "Core Library"
        direction TB
        CoreCipher["core/cipher.go"]:::core
        CorePacket["core/packet.go"]:::core
        CoreStream["core/stream.go"]:::core
    end

    %% AEAD Cipher Implementations
    subgraph "AEAD Cipher Implementations"
        direction TB
        AEADCipher["shadowaead/cipher.go"]:::core
        AEADPacket["shadowaead/packet.go"]:::core
        AEADStream["shadowaead/stream.go"]:::core
    end

    %% Protocol Helpers
    subgraph "Protocol Helpers"
        direction TB
        Socks["socks/socks.go"]:::core
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        TCP["tcp.go"]:::infra
        UDP["udp.go"]:::infra
        TCPDarwin["tcp_darwin.go"]:::infra
        TCPLinux["tcp_linux.go"]:::infra
        TCPOther["tcp_other.go"]:::infra
    end

    %% OS Integration
    subgraph "OS Integration"
        direction TB
        NFUtil["nfutil/"]:::infra
        PFUtil["pfutil/pf_darwin.go"]:::infra
    end

    %% Plugin Layer
    Plugin["plugin.go"]:::infra

    %% Demo Services
    subgraph "Demo Services"
        direction TB
        DemoGW["demo/gateway/main.go"]:::external
        DemoSocks["demo/tunnel/client/socks/main.go"]:::external
        DemoTCP["demo/tunnel/client/tcp/main.go"]:::external
        DemoServer["demo/tunnel/server/main.go"]:::external
    end

    %% Containerization & CI/CD
    DockerfileNode["Dockerfile"]:::external
    MakefileNode["Makefile"]:::external
    BuildYML[".github/workflows/build.yml"]:::external
    ReleaseYML[".github/workflows/release.yml"]:::external

    %% External Destination
    Dest["Destination Server"]:::external

    %% Connections
    Main -->|"loads config"| ConfigLoad
    Main --> ConfigTest
    ConfigLoad --> ClientConf
    ConfigLoad --> ServerConf

    Main -->|"spawns tunnels"| TCP
    Main -->|"spawns tunnels"| UDP

    TCP -->|"parse addr"| Socks
    UDP -->|"parse addr"| Socks

    TCP -->|"wrap conn"| CoreCipher
    UDP -->|"wrap conn"| CoreCipher

    CoreCipher --> CorePacket
    CoreCipher --> CoreStream
    CoreCipher --> AEADCipher
    AEADCipher --> AEADPacket
    AEADCipher --> AEADStream

    CoreStream -->|"io.Copy"| TCP
    CoreStream -->|"io.Copy"| UDP

    TCP --> Dest
    UDP --> Dest

    TCPDarwin -.-> TCP
    TCPLinux -.-> TCP
    TCPOther -.-> TCP

    NFUtil --> TCP
    PFUtil --> TCP

    Plugin -.-> CoreStream
    Plugin -.-> TCP

    DemoSocks --> Main
    DemoTCP --> Main
    Main --> DemoGW
    DemoGW --> DemoServer
    DemoServer --> Dest

    DockerfileNode -.-> Main
    DockerfileNode -.-> DemoGW
    MakefileNode -.-> Main

    BuildYML -.-> Main
    ReleaseYML -.-> Main

    %% Styles
    classDef app fill:#D6EAF8,stroke:#21618C,color:#1B2631
    classDef core fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef infra fill:#FAD7A0,stroke:#B9770E,color:#7E5109
    classDef external fill:#E5E8E8,stroke:#566573,color:#424949

    %% Click Events
    click Main "https://github.com/cuishuang/shadowsocks/blob/master/main.go"
    click ConfigLoad "https://github.com/cuishuang/shadowsocks/blob/master/configure.go"
    click ConfigTest "https://github.com/cuishuang/shadowsocks/blob/master/configure_test.go"
    click ClientConf "https://github.com/cuishuang/shadowsocks/blob/master/conf/client.json"
    click ServerConf "https://github.com/cuishuang/shadowsocks/blob/master/conf/server.json"
    click CoreCipher "https://github.com/cuishuang/shadowsocks/blob/master/core/cipher.go"
    click CorePacket "https://github.com/cuishuang/shadowsocks/blob/master/core/packet.go"
    click CoreStream "https://github.com/cuishuang/shadowsocks/blob/master/core/stream.go"
    click AEADCipher "https://github.com/cuishuang/shadowsocks/blob/master/shadowaead/cipher.go"
    click AEADPacket "https://github.com/cuishuang/shadowsocks/blob/master/shadowaead/packet.go"
    click AEADStream "https://github.com/cuishuang/shadowsocks/blob/master/shadowaead/stream.go"
    click Socks "https://github.com/cuishuang/shadowsocks/blob/master/socks/socks.go"
    click TCP "https://github.com/cuishuang/shadowsocks/blob/master/tcp.go"
    click UDP "https://github.com/cuishuang/shadowsocks/blob/master/udp.go"
    click TCPDarwin "https://github.com/cuishuang/shadowsocks/blob/master/tcp_darwin.go"
    click TCPLinux "https://github.com/cuishuang/shadowsocks/blob/master/tcp_linux.go"
    click TCPOther "https://github.com/cuishuang/shadowsocks/blob/master/tcp_other.go"
    click NFUtil "https://github.com/cuishuang/shadowsocks/tree/master/nfutil/"
    click PFUtil "https://github.com/cuishuang/shadowsocks/blob/master/pfutil/pf_darwin.go"
    click Plugin "https://github.com/cuishuang/shadowsocks/blob/master/plugin.go"
    click DemoGW "https://github.com/cuishuang/shadowsocks/blob/master/demo/gateway/main.go"
    click DemoSocks "https://github.com/cuishuang/shadowsocks/blob/master/demo/tunnel/client/socks/main.go"
    click DemoTCP "https://github.com/cuishuang/shadowsocks/blob/master/demo/tunnel/client/tcp/main.go"
    click DemoServer "https://github.com/cuishuang/shadowsocks/blob/master/demo/tunnel/server/main.go"
    click DockerfileNode "https://github.com/cuishuang/shadowsocks/tree/master/Dockerfile"
    click MakefileNode "https://github.com/cuishuang/shadowsocks/tree/master/Makefile"
    click BuildYML "https://github.com/cuishuang/shadowsocks/blob/master/.github/workflows/build.yml"
    click ReleaseYML "https://github.com/cuishuang/shadowsocks/blob/master/.github/workflows/release.yml"
```
