# apernet/hysteria architecture

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

- Interactive diagram: https://gitdiagram.com/apernet/hysteria
- Repository: https://github.com/apernet/hysteria

## Overview

##### Project type and purpose
- Hysteria is a high‑performance, censorship‑resistant proxy server and client built in Go.
- It provides multiple proxy modes (SOCKS5, HTTP proxy, TCP/UDP forwarding, TProxy, TUN), uses a custom QUIC‑based protocol for transport, and supports pluggable authentication, access control, and traffic logging.

##### File structure
- Top‑level “app” directory: contains the client and server command‑line interfaces (CLI), configuration loading, TLS setup, HTTP server, forwarding engines, multiplexing, redirect (packet socket), and TUN/TProxy implementations.
- “core” directory: implements the core protocol (QUIC‑based framing, congestion control algorithms), common utilities, fragmen­tation, PMTUD, client and server endpoint logic.
- “extras” directory: optional plugins (authentication methods, ACL‑based outbounds, MASQ, obfuscation, traffic sniffer, transport extensions).
- Build and CI config: Dockerfile, GitHub workflows, go.mod/go.work for multi‑module builds.
- Tests: unit tests in each package, integration tests under core/internal/integration_tests.

##### README for additional insights
- Confirms that Hysteria masquerades as HTTP/3, uses QUIC for performance/resistance, and is extensible with custom authentication, traffic statistics, and access control.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        ClientCLI["Client CLI"]:::client
        ConfigLoader["Config & Cert Loader"]:::client
        AuthPluginClient["Auth Plugin Hook"]:::plugin
        CoreClient["Core Client Library"]:::core
    end

    %% Network
    InternetCloud["Internet (QUIC/HTTP3 Tunnel)"]:::network

    %% Server Side
    subgraph "Server Side"
        direction TB
        ServerCore["Core Server Library"]:::core
        AuthHook["Authentication Hook"]:::plugin
        StreamMux["Stream Multiplexer (ProxyMux)"]:::core
        subgraph Engines
            direction TB
            HTTPProxy["HTTP Proxy Engine"]:::engine
            TCPForwarder["TCP Forwarder"]:::engine
            UDPForwarder["UDP Forwarder"]:::engine
            SOCKS5["SOCKS5 Proxy Engine"]:::engine
            TUN["TUN Interface"]:::sys
            TProxy["TProxy Implementation"]:::sys
            Redirect["Redirect Hook"]:::sys
        end
        subgraph OutboundPath
            direction TB
            OutboundPlugin["Outbound Plugin Hook"]:::plugin
            ExternalNet["External Network"]:::network
        end
    end

    %% Connections
    ClientCLI -->|"load config"| ConfigLoader
    ConfigLoader -->|"initialize TLS & auth"| AuthPluginClient
    AuthPluginClient -->|"invoke"| CoreClient
    CoreClient -->|"open QUIC session"| InternetCloud
    InternetCloud -->|"QUIC connection"| ServerCore
    ServerCore -->|"validate & auth"| AuthHook
    AuthHook -->|"demultiplex streams"| StreamMux
    StreamMux -->|"dispatch"| HTTPProxy
    StreamMux -->|"dispatch"| TCPForwarder
    StreamMux -->|"dispatch"| UDPForwarder
    StreamMux -->|"dispatch"| SOCKS5
    StreamMux -->|"dispatch"| TUN
    StreamMux -->|"dispatch"| TProxy
    StreamMux -->|"dispatch"| Redirect
    HTTPProxy -->|"outbound HTTP"| OutboundPlugin
    TCPForwarder -->|"outbound TCP"| OutboundPlugin
    UDPForwarder -->|"outbound UDP"| OutboundPlugin
    SOCKS5 -->|"outbound"| OutboundPlugin
    TUN -->|"inject packets"| ExternalNet
    TProxy -->|"redirect packets"| ExternalNet
    Redirect -->|"packet socket"| ExternalNet
    OutboundPlugin --> ExternalNet

    %% Click Events
    click ClientCLI "https://github.com/apernet/hysteria/blob/master/app/cmd/client.go"
    click ConfigLoader "https://github.com/apernet/hysteria/blob/master/app/internal/utils/certloader.go"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/client/client.go"
    click ServerCore "https://github.com/apernet/hysteria/blob/master/core/server/server.go"
    click HTTPProxy "https://github.com/apernet/hysteria/blob/master/app/internal/http/server.go"
    click TCPForwarder "https://github.com/apernet/hysteria/blob/master/app/internal/forwarding/tcp.go"
    click UDPForwarder "https://github.com/apernet/hysteria/blob/master/app/internal/forwarding/udp.go"
    click SOCKS5 "https://github.com/apernet/hysteria/blob/master/app/internal/socks5/server.go"
    click StreamMux "https://github.com/apernet/hysteria/blob/master/app/internal/proxymux/mux.go"
    click Redirect "https://github.com/apernet/hysteria/blob/master/app/internal/redirect/tcp_linux.go"
    click TProxy "https://github.com/apernet/hysteria/blob/master/app/internal/tproxy/tcp_linux.go"
    click TUN "https://github.com/apernet/hysteria/blob/master/app/internal/tun/server.go"
    click AuthPluginClient "https://github.com/apernet/hysteria/blob/master/extras/auth/http.go"
    click AuthHook "https://github.com/apernet/hysteria/blob/master/extras/auth/http.go"
    click OutboundPlugin "https://github.com/apernet/hysteria/blob/master/extras/outbounds/acl.go"
    click InternetCloud "https://github.com/apernet/hysteria/blob/master/core/internal/protocol/proxy.go"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/internal/protocol/proxy.go"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/internal/frag/frag.go"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/internal/pmtud/avail.go"
    click CoreClient "https://github.com/apernet/hysteria/tree/master/core/internal/congestion/bbr"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/internal/utils/qstream.go"
    click CoreClient "https://github.com/apernet/hysteria/blob/master/core/errors/errors.go"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#DFFFE0,stroke:#228A00,color:#228A00;
    classDef engine fill:#FFE7C0,stroke:#D2691E,color:#D2691E;
    classDef plugin fill:#F3E0FF,stroke:#8041B3,color:#8041B3;
    classDef sys fill:#E0E0E0,stroke:#707070,color:#707070;
    classDef network fill:#E0F7FF,stroke:#0096C7,color:#0096C7;
```
