# shadowsocks/shadowsocks-rust architecture

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

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

## Overview

##### Project Type and Purpose
This is a proxy server/client implementation written in Rust, specifically a port of the Shadowsocks protocol. It's a network tunneling tool designed to bypass firewalls using encrypted connections.

##### Main Components

A. Core Components:
- Local Client (sslocal)
- Remote Server (ssserver)
- Manager Service (ssmanager)
- Configuration System
- Crypto Engine

B. Protocol Support:
- SOCKS5/SOCKS4 Protocol Handler
- HTTP Proxy Protocol Handler
- Tunnel Protocol Handler
- DNS Protocol Handler
- Transparent Proxy (Redir) Handler
- TUN Interface Handler

C. Supporting Systems:
- Plugin System
- Load Balancer
- ACL (Access Control List)
- Logging System
- DNS Resolver

**[Client Side] <-----> [Encrypted Tunnel] <-----> [Server Side]**

##### Top Layer - User Interface
- Command-line interfaces (sslocal, ssserver, ssmanager)
- Configuration handlers
- Logging system

##### Middle Layer - Protocol Handlers
- SOCKS5/4 handlers
- HTTP proxy
- DNS servers
- Tunnel handlers
- TUN interface
- Transparent proxy

##### Core Layer
- Crypto engine
- Network handlers
- Plugin system
- Load balancer

##### Bottom Layer
- System interfaces
- Network stack integration

##### Key Elements to Highlight

a. Client Side:
- Multiple protocol support (SOCKS, HTTP, Tunnel, etc.)
- Plugin system integration
- Load balancing logic
- Local DNS resolver

b. Server Side:
- Multi-user support
- ACL implementation
- Manager API interface
- Remote DNS handling

c. Shared Components:
- AEAD cipher implementations
- Configuration management
- Logging system
- Plugin architecture

##### Implementation Details

Technical annotations for:
- Supported ciphers (AEAD 2022, AEAD, Stream)
- Protocol versions (SIP002, SIP003, SIP004, SIP022)
- Authentication methods
- Configuration formats

- Nested components
- Different connection types
- Clear labeling
- Expandable sections for detail views

Remember to:
- Version information
- Document all external dependencies

This will create a comprehensive yet understandable representation of the system's architecture while capturing the complexity of the Shadowsocks-rust implementation.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interface Layer"
        CLI1["Local Client"]:::cli
        CLI2["Remote Server"]:::cli
        CLI3["Manager Service"]:::cli
        Config["Configuration System"]:::config
        Logging["Logging System"]:::logging
    end

    subgraph "Protocol Handler Layer"
        SOCKS["SOCKS5/4 Handler"]:::protocol
        HTTP["HTTP Proxy"]:::protocol
        DNS["DNS Protocol"]:::protocol
        TUNNEL["Tunnel Protocol"]:::protocol
        TUN["TUN Interface"]:::protocol
        REDIR["Transparent Proxy"]:::protocol
    end

    subgraph "Core Layer"
        Crypto["Crypto Engine"]:::core
        Plugin["Plugin System"]:::core
        LoadBal["Load Balancer"]:::core
        ACL["ACL System"]:::core
        DNSRes["DNS Resolver"]:::core
    end

    subgraph "System Layer"
        Network["Network Stack"]:::system
        SysInt["System Interfaces"]:::system
    end

    %% Connections from UI to Protocol
    CLI1 --> SOCKS
    CLI1 --> HTTP
    CLI1 --> TUNNEL
    CLI1 --> TUN
    CLI1 --> REDIR
    CLI1 --> DNS
    
    CLI2 --> Network
    CLI3 --> Network
    
    Config --> CLI1
    Config --> CLI2
    Config --> CLI3
    
    Logging -.-> CLI1
    Logging -.-> CLI2
    Logging -.-> CLI3

    %% Connections from Protocol to Core
    SOCKS --> Crypto
    HTTP --> Crypto
    TUNNEL --> Crypto
    TUN --> Crypto
    REDIR --> Crypto
    DNS --> Crypto

    SOCKS --> LoadBal
    HTTP --> LoadBal
    TUNNEL --> LoadBal
    TUN --> LoadBal
    REDIR --> LoadBal

    %% Core Layer Interconnections
    Crypto --> Plugin
    LoadBal --> ACL
    DNS --> DNSRes
    
    %% Core to System Layer
    Crypto --> Network
    Plugin --> Network
    DNSRes --> Network
    
    ACL --> SysInt
    Network --> SysInt

    %% Click Events
    click CLI1 "https://github.com/shadowsocks/shadowsocks-rust/blob/master/bin/sslocal.rs"
    click CLI2 "https://github.com/shadowsocks/shadowsocks-rust/blob/master/bin/ssserver.rs"
    click CLI3 "https://github.com/shadowsocks/shadowsocks-rust/blob/master/bin/ssmanager.rs"
    click Config "https://github.com/shadowsocks/shadowsocks-rust/blob/master/src/config.rs"
    click Crypto "https://github.com/shadowsocks/shadowsocks-rust/blob/master/crates/shadowsocks/src/relay/tcprelay/crypto_io.rs"
    click SOCKS "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/socks/"
    click HTTP "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/http/"
    click TUNNEL "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/tunnel/"
    click DNS "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/dns/"
    click REDIR "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/redir/"
    click TUN "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/tun/"
    click Plugin "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks/src/plugin/"
    click LoadBal "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/local/loadbalancing/"
    click ACL "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks-service/src/acl/"
    click Logging "https://github.com/shadowsocks/shadowsocks-rust/tree/master/src/logging/"
    click DNSRes "https://github.com/shadowsocks/shadowsocks-rust/tree/master/crates/shadowsocks/src/dns_resolver/"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:2px
    classDef config fill:#ff9,stroke:#333,stroke-width:2px
    classDef logging fill:#999,stroke:#333,stroke-width:2px
    classDef protocol fill:#9f9,stroke:#333,stroke-width:2px
    classDef core fill:#99f,stroke:#333,stroke-width:2px
    classDef system fill:#f99,stroke:#333,stroke-width:2px

    %% Legend
    subgraph Legend
        CLI_L["CLI Components"]:::cli
        CONF_L["Configuration"]:::config
        LOG_L["Logging"]:::logging
        PROT_L["Protocol Handlers"]:::protocol
        CORE_L["Core Components"]:::core
        SYS_L["System Components"]:::system
    end
```
