# xtls/xray-core architecture

> Architecture diagram of the GitHub repository xtls/xray-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xtls/xray-core
- Repository: https://github.com/xtls/xray-core

## Overview

Project X (Xray-core) is a configurable network proxy and tunneling core. Its runtime handles inbound proxy traffic, routes requests, and forwards them through outbound handlers and network transports; configuration, DNS, policy, and operational features support that flow. The excerpts show concrete dispatch from several inbound handlers and show routing, policy, DNS, and multiplexing dependencies. Many protocol and observability capabilities are evident in the tree but were not sampled, so their connections are left unverified rather than inferred.

Main entry points: [`app/proxyman/inbound/worker.go`](https://github.com/xtls/xray-core/blob/main/app/proxyman/inbound/worker.go) (Inbound workers), [`app/router/router.go`](https://github.com/xtls/xray-core/blob/main/app/router/router.go) (Request routing), [`app/proxyman/outbound/handler.go`](https://github.com/xtls/xray-core/blob/main/app/proxyman/outbound/handler.go) (Outbound handlers), [`proxy/wireguard/server.go`](https://github.com/xtls/xray-core/blob/main/proxy/wireguard/server.go) (WireGuard proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Traffic runtime"]
  node_inbound["Inbound workers<br/>[worker.go]"]
  node_routing["Request routing<br/>[router.go]"]
  node_outbound["Outbound handlers<br/>[handler.go]"]
  node_transport["Network transports"]
  node_mux["Multiplexing<br/>[server.go]"]
end

subgraph group_protocols["Proxy protocols"]
  node_http["HTTP proxy<br/>[server.go]"]
  node_socks["SOCKS proxy<br/>[server.go]"]
  node_trojan["Trojan proxy<br/>[server.go]"]
  node_shadowsocks["Shadowsocks proxy<br/>[server.go]"]
  node_hysteria["Hysteria proxy<br/>[server.go]"]
  node_masque["MASQUE proxy<br/>[server.go]"]
  node_wireguard["WireGuard proxy<br/>[server.go]"]
end

subgraph group_services["Core services"]
  node_dns["DNS service<br/>[dns.go]"]
  node_dns_cache[("DNS cache")]
  node_policy["Policy manager<br/>[manager.go]"]
  node_config["Configuration loading<br/>[loader.go]"]
end

subgraph group_operations["Operations"]
  node_stats["Traffic statistics<br/>[stats.go]"]
  node_observatory["Health observation<br/>[observatory.go]"]
  node_api["Control API<br/>[api.go]"]
end

node_client(("Proxy client"))

node_client -.->|"opens connection"| node_inbound
node_inbound -.->|"handles HTTP"| node_http
node_inbound -.->|"handles SOCKS"| node_socks
node_inbound -.->|"handles Trojan"| node_trojan
node_inbound -.->|"handles Shadowsocks"| node_shadowsocks
node_inbound -.->|"handles Hysteria"| node_hysteria
node_inbound -.->|"handles MASQUE"| node_masque
node_inbound -.->|"handles WireGuard"| node_wireguard
node_http -->|"dispatches links"| node_routing
node_socks -->|"dispatches links"| node_routing
node_trojan -->|"dispatches packets"| node_routing
node_shadowsocks -->|"dispatches packets"| node_routing
node_hysteria -->|"dispatches links"| node_routing
node_wireguard -->|"dispatches links"| node_routing
node_masque -->|"uses tunnel support"| node_wireguard
node_routing -->|"uses DNS features"| node_dns
node_outbound -->|"uses multiplexing"| node_mux
node_outbound -->|"uses transports"| node_transport
node_inbound -->|"accepts connections"| node_transport
node_inbound -.->|"dispatches requests"| node_routing
node_outbound -->|"applies policy"| node_policy
node_dns -.->|"caches answers"| node_dns_cache
node_config -->|"builds rules"| node_routing
node_api -->|"queries statistics"| node_stats
node_observatory -.->|"observes routing"| node_routing

click node_inbound "https://github.com/xtls/xray-core/blob/main/app/proxyman/inbound/worker.go"
click node_routing "https://github.com/xtls/xray-core/blob/main/app/router/router.go"
click node_outbound "https://github.com/xtls/xray-core/blob/main/app/proxyman/outbound/handler.go"
click node_transport "https://github.com/xtls/xray-core/tree/main/transport/internet"
click node_mux "https://github.com/xtls/xray-core/blob/main/common/mux/server.go"
click node_http "https://github.com/xtls/xray-core/blob/main/proxy/http/server.go"
click node_socks "https://github.com/xtls/xray-core/blob/main/proxy/socks/server.go"
click node_trojan "https://github.com/xtls/xray-core/blob/main/proxy/trojan/server.go"
click node_shadowsocks "https://github.com/xtls/xray-core/blob/main/proxy/shadowsocks/server.go"
click node_hysteria "https://github.com/xtls/xray-core/blob/main/proxy/hysteria/server.go"
click node_masque "https://github.com/xtls/xray-core/blob/main/proxy/masque/server.go"
click node_wireguard "https://github.com/xtls/xray-core/blob/main/proxy/wireguard/server.go"
click node_dns "https://github.com/xtls/xray-core/blob/main/app/dns/dns.go"
click node_dns_cache "https://github.com/xtls/xray-core/blob/main/app/dns/cache_controller.go"
click node_policy "https://github.com/xtls/xray-core/blob/main/app/policy/manager.go"
click node_config "https://github.com/xtls/xray-core/blob/main/infra/conf/loader.go"
click node_stats "https://github.com/xtls/xray-core/blob/main/app/stats/stats.go"
click node_observatory "https://github.com/xtls/xray-core/blob/main/app/observatory/observatory.go"
click node_api "https://github.com/xtls/xray-core/blob/main/main/commands/all/api/api.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_inbound,node_routing,node_outbound,node_transport,node_mux,node_client toneBlue
class node_http,node_socks,node_trojan,node_shadowsocks,node_hysteria,node_masque,node_wireguard toneAmber
class node_dns,node_dns_cache,node_policy,node_config toneMint
class node_stats,node_observatory,node_api toneRose
```

## Components

### Traffic runtime

- [Inbound workers](https://github.com/xtls/xray-core/blob/main/app/proxyman/inbound/worker.go): `app/proxyman/inbound/worker.go`
- [Request routing](https://github.com/xtls/xray-core/blob/main/app/router/router.go): `app/router/router.go`
- [Outbound handlers](https://github.com/xtls/xray-core/blob/main/app/proxyman/outbound/handler.go): `app/proxyman/outbound/handler.go`
- [Network transports](https://github.com/xtls/xray-core/tree/main/transport/internet): `transport/internet`
- [Multiplexing](https://github.com/xtls/xray-core/blob/main/common/mux/server.go): `common/mux/server.go`

### Proxy protocols

- [HTTP proxy](https://github.com/xtls/xray-core/blob/main/proxy/http/server.go): `proxy/http/server.go`
- [SOCKS proxy](https://github.com/xtls/xray-core/blob/main/proxy/socks/server.go): `proxy/socks/server.go`
- [Trojan proxy](https://github.com/xtls/xray-core/blob/main/proxy/trojan/server.go): `proxy/trojan/server.go`
- [Shadowsocks proxy](https://github.com/xtls/xray-core/blob/main/proxy/shadowsocks/server.go): `proxy/shadowsocks/server.go`
- [Hysteria proxy](https://github.com/xtls/xray-core/blob/main/proxy/hysteria/server.go): `proxy/hysteria/server.go`
- [MASQUE proxy](https://github.com/xtls/xray-core/blob/main/proxy/masque/server.go): `proxy/masque/server.go`
- [WireGuard proxy](https://github.com/xtls/xray-core/blob/main/proxy/wireguard/server.go): `proxy/wireguard/server.go`

### Core services

- [DNS service](https://github.com/xtls/xray-core/blob/main/app/dns/dns.go): `app/dns/dns.go`
- [DNS cache](https://github.com/xtls/xray-core/blob/main/app/dns/cache_controller.go): `app/dns/cache_controller.go`
- [Policy manager](https://github.com/xtls/xray-core/blob/main/app/policy/manager.go): `app/policy/manager.go`
- [Configuration loading](https://github.com/xtls/xray-core/blob/main/infra/conf/loader.go): `infra/conf/loader.go`

### Operations

- [Traffic statistics](https://github.com/xtls/xray-core/blob/main/app/stats/stats.go): `app/stats/stats.go`
- [Health observation](https://github.com/xtls/xray-core/blob/main/app/observatory/observatory.go): `app/observatory/observatory.go`
- [Control API](https://github.com/xtls/xray-core/blob/main/main/commands/all/api/api.go): `main/commands/all/api/api.go`

### Other components

- **Proxy client**

## Connections

- Proxy client → Inbound workers: opens connection
- Inbound workers → HTTP proxy: handles HTTP
- Inbound workers → SOCKS proxy: handles SOCKS
- Inbound workers → Trojan proxy: handles Trojan
- Inbound workers → Shadowsocks proxy: handles Shadowsocks
- Inbound workers → Hysteria proxy: handles Hysteria
- Inbound workers → MASQUE proxy: handles MASQUE
- Inbound workers → WireGuard proxy: handles WireGuard
- HTTP proxy → Request routing: dispatches links (evidence: `proxy/http/server.go`)
- SOCKS proxy → Request routing: dispatches links (evidence: `proxy/socks/server.go`)
- Trojan proxy → Request routing: dispatches packets (evidence: `proxy/trojan/server.go`)
- Shadowsocks proxy → Request routing: dispatches packets (evidence: `proxy/shadowsocks/server.go`)
- Hysteria proxy → Request routing: dispatches links (evidence: `proxy/hysteria/server.go`)
- WireGuard proxy → Request routing: dispatches links (evidence: `proxy/wireguard/server.go`)
- MASQUE proxy → WireGuard proxy: uses tunnel support (evidence: `proxy/masque/server.go`)
- Request routing → DNS service: uses DNS features (evidence: `app/router/router.go`)
- Outbound handlers → Multiplexing: uses multiplexing (evidence: `app/proxyman/outbound/handler.go`)
- Outbound handlers → Network transports: uses transports (evidence: `app/proxyman/outbound/handler.go`)
- Inbound workers → Network transports: accepts connections (evidence: `app/proxyman/inbound/worker.go`)
- Inbound workers → Request routing: dispatches requests
- Outbound handlers → Policy manager: applies policy (evidence: `app/proxyman/outbound/handler.go`)
- DNS service → DNS cache: caches answers
- Configuration loading → Request routing: builds rules
- Control API → Traffic statistics: queries statistics
- Health observation → Request routing: observes routing
