# remnawave/xtls-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/remnawave/xtls-sdk
- Repository: https://github.com/remnawave/xtls-sdk

## Overview

XTLS SDK is a TypeScript client for XRAY Core’s gRPC API. Callers use the client’s handler, router, and statistics services to manage inbound users and routing rules and retrieve system, user, inbound, outbound, and connection statistics. The services make gRPC calls and return typed SDK responses; generated protobuf modules define the wire messages, while user decoding and response models shape returned data. Edges reflect the README, source index, and excerpts; unsampled implementation details are not inferred.

Main entry points: [`src/common/utils/decode-user/decode-user.ts`](https://github.com/remnawave/xtls-sdk/blob/main/src/common/utils/decode-user/decode-user.ts) (User decoder), [`src/handler/handler.service.ts`](https://github.com/remnawave/xtls-sdk/blob/main/src/handler/handler.service.ts) (HandlerService), [`src/stats/stats.service.ts`](https://github.com/remnawave/xtls-sdk/blob/main/src/stats/stats.service.ts) (StatsService), [`src/router/router.service.ts`](https://github.com/remnawave/xtls-sdk/blob/main/src/router/router.service.ts) (RouterService)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["SDK API"]
  node_client["XtlsApi<br/>[index.ts]"]
end

subgraph group_users["User Management"]
  node_handler["HandlerService<br/>[handler.service.ts]"]
  node_user_decode["User decoder<br/>[decode-user.ts]"]
  node_user_models["User response models"]
  node_typed_helper["Typed-message helper"]
end

subgraph group_monitoring["Statistics"]
  node_stats["StatsService<br/>[stats.service.ts]"]
  node_stats_models["Statistics response models"]
end

subgraph group_routing["Routing"]
  node_router["RouterService<br/>[router.service.ts]"]
end

subgraph group_wire["Protobuf Types"]
  node_user_proto["Protocol user<br/>[user.ts]"]
  node_typed_proto["Typed message<br/>[typed_message.ts]"]
  node_proxyman_proto["Handler commands<br/>[command.ts]"]
  node_http_proto["HTTP account<br/>[config.ts]"]
  node_ss_proto["Shadowsocks account<br/>[config.ts]"]
  node_ss22_proto["Shadowsocks 2022 account<br/>[config.ts]"]
  node_socks_proto["SOCKS account<br/>[config.ts]"]
  node_trojan_proto["Trojan account<br/>[config.ts]"]
  node_vless_proto["VLESS account<br/>[account.ts]"]
  node_stats_proto["Statistics commands<br/>[command.ts]"]
  node_router_proto["Routing commands<br/>[command.ts]"]
  node_registry["Message registry<br/>[typeRegistry.ts]"]
end

node_caller(("SDK caller"))
node_xray["XRAY Core gRPC"]

node_caller -->|"creates"| node_client
node_client -->|"exposes"| node_handler
node_client -->|"exposes"| node_stats
node_client -->|"exposes"| node_router
node_caller -->|"manages users"| node_handler
node_caller -->|"requests stats"| node_stats
node_caller -.->|"manages rules"| node_router
node_handler -->|"calls gRPC"| node_xray
node_stats -->|"calls gRPC"| node_xray
node_router -->|"calls gRPC"| node_xray
node_handler -->|"uses commands"| node_proxyman_proto
node_stats -->|"uses commands"| node_stats_proto
node_router -->|"uses commands"| node_router_proto
node_handler -->|"builds messages"| node_typed_helper
node_typed_helper -->|"creates"| node_typed_proto
node_proxyman_proto -->|"encodes user"| node_user_proto
node_user_proto -->|"encodes account"| node_typed_proto
node_user_models -->|"decodes users"| node_user_decode
node_user_decode -->|"reads user"| node_user_proto
node_user_decode -->|"maps account"| node_http_proto
node_user_decode -->|"maps account"| node_ss_proto
node_user_decode -->|"maps account"| node_ss22_proto
node_user_decode -->|"maps account"| node_socks_proto
node_user_decode -->|"maps account"| node_trojan_proto
node_user_decode -->|"maps account"| node_vless_proto
node_stats -->|"returns models"| node_stats_models
node_stats_models -->|"models responses"| node_stats_proto
node_router -->|"removes rules"| node_router_proto
node_user_proto -->|"registers type"| node_registry
node_typed_proto -->|"registers type"| node_registry
node_proxyman_proto -->|"uses registry"| node_registry
node_router_proto -->|"uses registry"| node_registry
node_stats_proto -->|"uses registry"| node_registry

click node_client "https://github.com/remnawave/xtls-sdk/blob/main/index.ts"
click node_handler "https://github.com/remnawave/xtls-sdk/blob/main/src/handler/handler.service.ts"
click node_user_decode "https://github.com/remnawave/xtls-sdk/blob/main/src/common/utils/decode-user/decode-user.ts"
click node_user_models "https://github.com/remnawave/xtls-sdk/blob/main/src/handler/models/get-inbound-users/get-inbound-users.response.model.ts"
click node_typed_helper "https://github.com/remnawave/xtls-sdk/blob/main/src/common/utils/create-typed-message/create-typed-message.ts"
click node_user_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/common/protocol/user.ts"
click node_typed_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/common/serial/typed_message.ts"
click node_proxyman_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/proxyman/command/command.ts"
click node_http_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/http/config.ts"
click node_ss_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/shadowsocks/config.ts"
click node_ss22_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/shadowsocks_2022/config.ts"
click node_socks_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/socks/config.ts"
click node_trojan_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/trojan/config.ts"
click node_vless_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/vless/account.ts"
click node_stats "https://github.com/remnawave/xtls-sdk/blob/main/src/stats/stats.service.ts"
click node_stats_models "https://github.com/remnawave/xtls-sdk/tree/main/src/stats/models"
click node_stats_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/stats/command/command.ts"
click node_router "https://github.com/remnawave/xtls-sdk/blob/main/src/router/router.service.ts"
click node_router_proto "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/router/command/command.ts"
click node_registry "https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/typeRegistry.ts"

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_client toneBlue
class node_handler,node_user_decode,node_user_models,node_typed_helper toneAmber
class node_stats,node_stats_models toneMint
class node_router toneRose
class node_user_proto,node_typed_proto,node_proxyman_proto,node_http_proto,node_ss_proto,node_ss22_proto,node_socks_proto,node_trojan_proto,node_vless_proto,node_stats_proto,node_router_proto,node_registry,node_caller,node_xray toneIndigo
```

## Components

### SDK API

- [XtlsApi](https://github.com/remnawave/xtls-sdk/blob/main/index.ts): `index.ts`

### User Management

- [HandlerService](https://github.com/remnawave/xtls-sdk/blob/main/src/handler/handler.service.ts): `src/handler/handler.service.ts`
- [User decoder](https://github.com/remnawave/xtls-sdk/blob/main/src/common/utils/decode-user/decode-user.ts): `src/common/utils/decode-user/decode-user.ts`
- [User response models](https://github.com/remnawave/xtls-sdk/blob/main/src/handler/models/get-inbound-users/get-inbound-users.response.model.ts): `src/handler/models/get-inbound-users/get-inbound-users.response.model.ts`
- [Typed-message helper](https://github.com/remnawave/xtls-sdk/blob/main/src/common/utils/create-typed-message/create-typed-message.ts): `src/common/utils/create-typed-message/create-typed-message.ts`

### Statistics

- [StatsService](https://github.com/remnawave/xtls-sdk/blob/main/src/stats/stats.service.ts): `src/stats/stats.service.ts`
- [Statistics response models](https://github.com/remnawave/xtls-sdk/tree/main/src/stats/models): `src/stats/models`

### Routing

- [RouterService](https://github.com/remnawave/xtls-sdk/blob/main/src/router/router.service.ts): `src/router/router.service.ts`

### Protobuf Types

- [Protocol user](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/common/protocol/user.ts): `src/xray-protos/common/protocol/user.ts`
- [Typed message](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/common/serial/typed_message.ts): `src/xray-protos/common/serial/typed_message.ts`
- [Handler commands](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/proxyman/command/command.ts): `src/xray-protos/app/proxyman/command/command.ts`
- [HTTP account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/http/config.ts): `src/xray-protos/proxy/http/config.ts`
- [Shadowsocks account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/shadowsocks/config.ts): `src/xray-protos/proxy/shadowsocks/config.ts`
- [Shadowsocks 2022 account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/shadowsocks_2022/config.ts): `src/xray-protos/proxy/shadowsocks_2022/config.ts`
- [SOCKS account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/socks/config.ts): `src/xray-protos/proxy/socks/config.ts`
- [Trojan account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/trojan/config.ts): `src/xray-protos/proxy/trojan/config.ts`
- [VLESS account](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/proxy/vless/account.ts): `src/xray-protos/proxy/vless/account.ts`
- [Statistics commands](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/stats/command/command.ts): `src/xray-protos/app/stats/command/command.ts`
- [Routing commands](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/app/router/command/command.ts): `src/xray-protos/app/router/command/command.ts`
- [Message registry](https://github.com/remnawave/xtls-sdk/blob/main/src/xray-protos/typeRegistry.ts): `src/xray-protos/typeRegistry.ts`

### Other components

- **SDK caller**
- **XRAY Core gRPC**

## Connections

- SDK caller → XtlsApi: creates (evidence: `README.md`)
- XtlsApi → HandlerService: exposes (evidence: `index.ts`)
- XtlsApi → StatsService: exposes (evidence: `index.ts`)
- XtlsApi → RouterService: exposes (evidence: `index.ts`)
- SDK caller → HandlerService: manages users (evidence: `README.md`)
- SDK caller → StatsService: requests stats (evidence: `README.md`)
- SDK caller → RouterService: manages rules
- HandlerService → XRAY Core gRPC: calls gRPC (evidence: `src/handler/handler.service.ts`)
- StatsService → XRAY Core gRPC: calls gRPC (evidence: `src/stats/stats.service.ts`)
- RouterService → XRAY Core gRPC: calls gRPC (evidence: `src/router/router.service.ts`)
- HandlerService → Handler commands: uses commands (evidence: `src/handler/handler.service.ts`)
- StatsService → Statistics commands: uses commands (evidence: `src/stats/stats.service.ts`)
- RouterService → Routing commands: uses commands (evidence: `src/router/router.service.ts`)
- HandlerService → Typed-message helper: builds messages (evidence: `src/handler/handler.service.ts`)
- Typed-message helper → Typed message: creates (evidence: `src/common/utils/create-typed-message/create-typed-message.ts`)
- Handler commands → Protocol user: encodes user (evidence: `src/xray-protos/app/proxyman/command/command.ts`)
- Protocol user → Typed message: encodes account (evidence: `src/xray-protos/common/protocol/user.ts`)
- User response models → User decoder: decodes users (evidence: `src/handler/models/get-inbound-users/get-inbound-users.response.model.ts`)
- User decoder → Protocol user: reads user (evidence: `src/common/utils/decode-user/decode-user.ts`)
- User decoder → HTTP account: maps account
- User decoder → Shadowsocks account: maps account
- User decoder → Shadowsocks 2022 account: maps account
- User decoder → SOCKS account: maps account
- User decoder → Trojan account: maps account
- User decoder → VLESS account: maps account
- StatsService → Statistics response models: returns models (evidence: `src/stats/stats.service.ts`)
- Statistics response models → Statistics commands: models responses (evidence: `src/stats/models/get-all-inbounds-stats/get-all-inbounds-stats.response.model.ts`)
- RouterService → Routing commands: removes rules (evidence: `src/router/router.service.ts`)
- Protocol user → Message registry: registers type (evidence: `src/xray-protos/common/protocol/user.ts`)
- Typed message → Message registry: registers type (evidence: `src/xray-protos/common/serial/typed_message.ts`)
- Handler commands → Message registry: uses registry (evidence: `src/xray-protos/app/proxyman/command/command.ts`)
- Routing commands → Message registry: uses registry (evidence: `src/xray-protos/app/router/command/command.ts`)
- Statistics commands → Message registry: uses registry (evidence: `src/xray-protos/app/stats/command/command.ts`)
