# trojan-gfw/trojan architecture

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

- Interactive diagram: https://gitdiagram.com/trojan-gfw/trojan
- Repository: https://github.com/trojan-gfw/trojan

## Overview

##### Project type and purpose
- This is a C++ network proxy tool (called “Trojan”) designed to bypass the Great Firewall by encapsulating traffic in TLS and mimicking common protocols.
- It’s neither a traditional web app nor a database-backed service; it’s a high-performance client/server networking application with pluggable protocols and optional MySQL-based authentication.

##### File structure
- Top-level build and config: CMakeLists.txt, cmake/, Dockerfile, azure-pipelines.yml, .gitpod.*
- Source code under src/ subdivided into:
- core/ – configuration, logging, versioning, generic service abstractions
- proto/ – protocol definitions (Trojan requests, SOCKS5, UDP payloads)
- session/ – concrete session handlers (client, server, forward, NAT, UDP)
- ssl/ – TLS session abstraction with default parameters
- main.cpp – CLI entrypoint
- examples/ – JSON template files for client/server configuration
- docs/ – user and protocol documentation
- tests/ – smoke tests invoking client/server configurations

##### README for additional insights
- The tool supports multiple “protocols over TLS,” uses Boost.Asio, OpenSSL, and optionally MySQL for authentication.
- It’s built with CMake and tested via shell scripts (LinuxSmokeTest).

##### Components
a. Main components:
- Client binary (Trojan client)
- Server binary (Trojan server)
- Core library (config loader, logger, service manager)
- Protocol layer (Trojan protocol, SOCKS5, UDP)
- Session layer (ClientSession, ServerSession, ForwardSession, NATSession, UDPForwardSession)
- TLS/SSL layer (SSLSession, policy defaults)
- External services: MySQL (optional), DNS, network endpoints
b. Relationships and interactions:
- Client → TLS handshake → Server
- Within each binary: main() invokes core::Service to spawn listener(s)
- Incoming TLS records passed to ssl::SSLSession → parsed by proto layer → handed off to appropriate session
- Session uses core::Config for routing and log for diagnostics
- Optional auth module queries MySQL over secure channel
c. Architectural patterns / principles:
- Layered architecture: Transport (TCP/TLS) → Protocol → Session → Service orchestration
- Plugin-like handling of different session types (polymorphic Session interface)
- Configuration-driven: examples/*.json define listener, upstream targets, passwords, plugin paths
d. Key technologies:
- Boost.Asio (async I/O)
- OpenSSL (TLS)
- CMake (build)
- Optional: libmysqlclient

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Trojan Entrypoint
    Entry["src/main.cpp"]:::artifact
    click Entry "https://github.com/trojan-gfw/trojan/blob/master/src/main.cpp"

    %% Client and Server Modes
    subgraph "Client Mode"
        ClientListener["SOCKS5 Listener"]:::protocol
        CLSession["ClientSession"]:::session
    end
    subgraph "Server Mode"
        TLSListener["TLS Listener"]:::protocol
        SVSession["ServerSession"]:::session
    end

    Entry -->|startup| ClientListener
    Entry -->|startup| TLSListener
    ClientListener -->|hands off| CLSession
    TLSListener -->|hands off| SVSession

    %% Core Library
    subgraph "Core Library"
        Config["config"]:::core-lib
        Logger["log"]:::core-lib
        ServiceMgr["service"]:::core-lib
        Version["version"]:::core-lib
        Auth["authenticator"]:::core-lib
    end
    click Config "https://github.com/trojan-gfw/trojan/blob/master/src/core/config.cpp"
    click Logger "https://github.com/trojan-gfw/trojan/blob/master/src/core/log.cpp"
    click ServiceMgr "https://github.com/trojan-gfw/trojan/blob/master/src/core/service.cpp"
    click Version "https://github.com/trojan-gfw/trojan/blob/master/src/core/version.cpp"
    click Auth "https://github.com/trojan-gfw/trojan/blob/master/src/core/authenticator.cpp"
    click Auth "https://github.com/trojan-gfw/trojan/blob/master/src/core/authenticator.h"
    click FindMySQL "https://github.com/trojan-gfw/trojan/blob/master/cmake/FindMySQL.cmake"

    CLSession -->|uses| Config
    CLSession -->|logs to| Logger
    CLSession -->|manages via| ServiceMgr
    SVSession -->|uses| Config
    SVSession -->|logs to| Logger
    SVSession -->|manages via| ServiceMgr
    SVSession -->|auth request| Auth

    %% Protocol Layer
    subgraph "Protocol Layer"
        TrojanProto["trojanrequest"]:::protocol
        SOCKS5["socks5address"]:::protocol
        UDPProto["udppacket"]:::protocol
    end
    click TrojanProto "https://github.com/trojan-gfw/trojan/blob/master/src/proto/trojanrequest.cpp"
    click SOCKS5 "https://github.com/trojan-gfw/trojan/blob/master/src/proto/socks5address.cpp"
    click UDPProto "https://github.com/trojan-gfw/trojan/blob/master/src/proto/udppacket.cpp"

    CLSession -->|decodes| TrojanProto
    CLSession -->|decodes| SOCKS5
    CLSession -->|decodes| UDPProto
    SVSession -->|decodes| TrojanProto
    SVSession -->|decodes| SOCKS5
    SVSession -->|decodes| UDPProto

    %% SSL Layer
    subgraph "SSL Layer"
        SSL["sslsession"]:::ssl
        Defaults["ssldefaults"]:::ssl
    end
    click SSL "https://github.com/trojan-gfw/trojan/blob/master/src/ssl/sslsession.cpp"
    click Defaults "https://github.com/trojan-gfw/trojan/blob/master/src/ssl/ssldefaults.cpp"

    ClientListener -->|TLS handshake| SSL
    TLSListener -->|TLS handshake| SSL
    SSL -->|records| TrojanProto

    %% External Services
    subgraph "External Services"
        MySQL["MySQL (optional)"]:::external
        DNS["DNS Resolver"]:::external
        Dest["Real Destination"]:::external
    end
    Auth -->|SQL query| MySQL
    CLSession -->|DNS lookup| DNS
    SVSession -->|forwards traffic| Dest

    %% Configuration Examples
    subgraph "Examples (JSON)"
        EJ1["client.json-example"]:::artifact
        EJ2["server.json-example"]:::artifact
        EJ3["forward.json-example"]:::artifact
        EJ4["nat.json-example"]:::artifact
        EJ5["trojan.service-example"]:::artifact
    end
    click EJ1 "https://github.com/trojan-gfw/trojan/blob/master/examples/client.json-example"
    click EJ2 "https://github.com/trojan-gfw/trojan/blob/master/examples/server.json-example"
    click EJ3 "https://github.com/trojan-gfw/trojan/blob/master/examples/forward.json-example"
    click EJ4 "https://github.com/trojan-gfw/trojan/blob/master/examples/nat.json-example"
    click EJ5 "https://github.com/trojan-gfw/trojan/blob/master/examples/trojan.service-example"
    Entry --> EJ1
    Entry --> EJ2

    %% Build & CI
    subgraph "Build & CI" 
        CMake["CMakeLists.txt"]:::artifact
        CMDir["cmake/"]:::artifact
        Dockerfile["Dockerfile"]:::artifact
        Azure["azure-pipelines.yml"]:::artifact
        GitpodDocker[".gitpod.Dockerfile"]:::artifact
        GitpodYml[".gitpod.yml"]:::artifact
    end
    click CMake "https://github.com/trojan-gfw/trojan/blob/master/CMakeLists.txt"
    click CMDir "https://github.com/trojan-gfw/trojan/tree/master/cmake/"
    Entry --> CMake

    %% Documentation
    subgraph "Documentation"
        D1["docs/overview.md"]:::artifact
        D2["docs/config.md"]:::artifact
        D3["docs/protocol.md"]:::artifact
        D4["docs/authenticator.md"]:::artifact
        D5["docs/usage.md"]:::artifact
    end
    click D1 "https://github.com/trojan-gfw/trojan/blob/master/docs/overview.md"
    click D2 "https://github.com/trojan-gfw/trojan/blob/master/docs/config.md"

    %% Smoke Tests
    subgraph "Tests"
        T1["tests/LinuxSmokeTest/basic.sh"]:::artifact
        T2["tests/LinuxSmokeTest/client.json"]:::artifact
        T3["tests/LinuxSmokeTest/server.json"]:::artifact
        T4["tests/LinuxSmokeTest/forward.json"]:::artifact
        T5["tests/LinuxSmokeTest/fake-client.sh"]:::artifact
        T6["tests/LinuxSmokeTest/fake-client.json"]:::artifact
    end
    click T1 "https://github.com/trojan-gfw/trojan/blob/master/tests/LinuxSmokeTest/basic.sh"
    click T2 "https://github.com/trojan-gfw/trojan/blob/master/tests/LinuxSmokeTest/client.json"

    %% Styles
    classDef core-lib fill:#D0E1FF,stroke:#0376FC,color:#000
    classDef protocol fill:#DFFFD0,stroke:#3C9C00,color:#000
    classDef session fill:#D0FFDFF,stroke:#009C72,color:#000
    classDef ssl fill:#F0F8FF,stroke:#00509E,color:#000
    classDef external fill:#FFF8C6,stroke:#D4A017,color:#000
    classDef artifact fill:#F2F2F2,stroke:#A9A9A9,color:#000
```
