Architecture Overview

Xray-core is a modular network proxy platform written in Go. It processes network traffic through a pipeline of inbound → dispatcher → router → outbound, with pluggable protocols at each end and configurable transport underneath.

Project Structure

xray-core/
  core/          # Instance, config loading, lifecycle
  app/           # Application-level features
    dispatcher/  # Central dispatcher (inbound→routing→outbound)
    proxyman/    # Inbound/outbound handler managers
    router/      # Routing engine, rules, balancers
    dns/         # DNS resolver, Fake-IP
    policy/      # Timeout and buffer policies
    stats/       # Traffic statistics
    commander/   # gRPC management API
    reverse/     # Reverse proxy tunnel
    observatory/ # Health checking
  common/        # Shared utilities
    buf/         # Buffer pool (8KB chunks)
    net/         # Network primitives (Address, Destination)
    protocol/    # Protocol abstractions (RequestHeader, AddressParser)
    session/     # Session context (Inbound, Outbound, Content)
    mux/         # Stream multiplexing
    xudp/        # UDP-over-mux with per-packet addressing
    signal/      # Notifier, ActivityTimer, Done
    strmatcher/  # String/domain matching (full, domain, substr, regex, MPH)
    crypto/      # AES, ChaCha20, etc.
    singbridge/  # sing-box library bridge
  features/      # Feature interfaces (traits/protocols)
    dns/         # dns.Client, dns.FakeDNSEngine interfaces
    inbound/     # inbound.Manager, inbound.Handler interfaces
    outbound/    # outbound.Manager, outbound.Handler interfaces
    routing/     # routing.Dispatcher, routing.Router interfaces
    policy/      # policy.Manager interface
    stats/       # stats.Manager interface
  proxy/         # Protocol implementations
    vless/       # VLESS (with Vision, XUDP, reverse)
    vmess/       # VMess (AEAD)
    trojan/      # Trojan
    shadowsocks/ # Shadowsocks (classic)
    shadowsocks_2022/ # Shadowsocks 2022
    socks/       # SOCKS5
    http/        # HTTP proxy
    dokodemo/    # Transparent proxy (dokodemo-door)
    freedom/     # Direct outbound
    blackhole/   # Null outbound
    dns/         # DNS proxy
    loopback/    # Re-enter routing
    wireguard/   # WireGuard tunnel
    hysteria/    # Hysteria2
    tun/         # TUN device + gVisor IP stack
  transport/     # Transport layer
    internet/    # Transport registry + implementations
      tcp/       # TCP
      websocket/ # WebSocket
      grpc/      # gRPC (gun)
      httpupgrade/ # HTTP Upgrade
      splithttp/ # Split HTTP
      kcp/       # mKCP (UDP reliable)
      tls/       # TLS + uTLS
      reality/   # REALITY
      hysteria/  # QUIC (Hysteria transport)
      udp/       # UDP dispatcher
    pipe/        # Internal pipe (Reader↔Writer)
  infra/conf/    # JSON config → protobuf conversion

High-Level Data Flow

flowchart LR
    Client([Client]) -->|TCP/UDP| Inbound

    subgraph Xray["Xray-core Instance"]
        Inbound["Inbound Handler<br/>(VLESS/VMess/Trojan/...)"]
        Dispatcher["Dispatcher<br/>(sniffing + routing)"]
        Router["Router<br/>(rules + balancer)"]
        Outbound["Outbound Handler<br/>(Freedom/VLESS/VMess/...)"]

        Inbound -->|"Dispatch(ctx, dest)"| Dispatcher
        Dispatcher -->|"PickRoute(ctx)"| Router
        Router -->|outbound tag| Dispatcher
        Dispatcher -->|"Dispatch(ctx, link)"| Outbound
    end

    Outbound -->|Transport| Server([Remote Server])

Key Dependencies

Dependency	Purpose
google.golang.org/protobuf	Config serialization
google.golang.org/grpc	gRPC transport + Commander API
gvisor.dev/gvisor	Userspace TCP/IP stack (for TUN)
github.com/gorilla/websocket	WebSocket transport
github.com/apernet/quic-go	QUIC transport (Hysteria)
github.com/refraction-networking/utls	TLS fingerprinting
github.com/xtls/reality	REALITY protocol
github.com/sagernet/sing-shadowsocks	Shadowsocks 2022
github.com/miekg/dns	DNS message parsing
golang.zx2c4.com/wireguard	WireGuard implementation
lukechampine.com/blake3	BLAKE3 hash (XUDP GlobalID)

Design Principles

1. Protobuf-first config: All configuration is defined as protobuf messages. JSON is just a serialization format that gets converted to protobuf at load time.

2. Feature registry: Components register themselves via common.RegisterConfig() with their protobuf config type. The Instance resolves dependencies automatically.

3. Interface-driven: Core contracts are defined in features/ as Go interfaces. Implementations in app/ and proxy/ satisfy these interfaces.

4. Pipe-based data flow: Inbound and outbound are connected through transport/pipe, providing backpressure-aware buffered channels.

5. Context-heavy: Session metadata (source, destination, user, tags, sniffing config) flows through context.Context via typed keys.