# mhsanaei/3x-ui architecture

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

- Interactive diagram: https://gitdiagram.com/mhsanaei/3x-ui
- Repository: https://github.com/mhsanaei/3x-ui

## Overview

3X-UI is a web control panel for configuring and monitoring Xray servers, clients, and proxy/VPN services across one or more nodes. Operators use the panel to manage protocol configuration and server state; subscribers can also request generated configuration links and subscription formats. The graph covers the UI, API/service layer, persistence, proxy runtimes, and subscription delivery. Connections are limited to README statements and SOURCE INDEX references or shown calls; several documented feature areas are represented by their existing directories because their implementation was not sampled.

Main entry points: [`internal/web/service/server.go`](https://github.com/mhsanaei/3x-ui/blob/main/internal/web/service/server.go) (Panel operations), [`frontend/src/pages/index/IndexPage.tsx`](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/index/IndexPage.tsx) (Management UI), [`internal/sub/controller.go`](https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/controller.go) (Subscription endpoints), [`main.go`](https://github.com/mhsanaei/3x-ui/blob/main/main.go) (Application startup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_frontend["Management UI<br/>[IndexPage.tsx]"]
  node_client_ui["Client management<br/>[ClientsPage.tsx]"]
  node_inbound_ui["Inbound configuration<br/>[InboundsPage.tsx]"]
  node_xray_ui["Routing and outbounds"]
  node_node_ui["Node management<br/>[NodesPage.tsx]"]
  node_settings_ui["Panel settings<br/>[SettingsPage.tsx]"]
end

subgraph group_api["Panel services"]
  node_api_controller["HTTP API<br/>[server.go]"]
  node_panel_service["Panel operations<br/>[server.go]"]
  node_web_entry["Application startup<br/>[main.go]"]
end

subgraph group_runtime["Proxy runtime"]
  node_xray_core["Xray management<br/>[server.go]"]
  node_amnezia_runtime["AmneziaWG runtime<br/>[manager.go]"]
  node_tuic_runtime["TUIC server<br/>[server.go]"]
  node_mtproto_runtime["MTProto manager<br/>[manager.go]"]
end

subgraph group_subs["Subscription delivery"]
  node_subscription_http["Subscription endpoints<br/>[controller.go]"]
  node_subscription_service["Subscription generation<br/>[service.go]"]
  node_clash_output["Clash output<br/>[clash_service.go]"]
end

subgraph group_state["Persistence and events"]
  node_database[("SQLite or PostgreSQL<br/>[db.go]")]
  node_event_bus["Event bus<br/>[bus.go]"]
end

node_operator(("Panel operator"))
node_subscriber(("Subscription client"))
node_external_proxy["Xray-core"]

node_operator -->|"manages"| node_frontend
node_frontend -.->|"opens"| node_client_ui
node_frontend -.->|"opens"| node_inbound_ui
node_frontend -.->|"opens"| node_xray_ui
node_frontend -.->|"opens"| node_node_ui
node_frontend -.->|"opens"| node_settings_ui
node_web_entry -->|"starts"| node_panel_service
node_web_entry -->|"starts"| node_subscription_http
node_api_controller -->|"delegates"| node_panel_service
node_panel_service -->|"reads and writes"| node_database
node_panel_service -.->|"manages"| node_xray_core
node_panel_service -->|"configures"| node_amnezia_runtime
node_panel_service -.->|"configures"| node_tuic_runtime
node_panel_service -.->|"configures"| node_mtproto_runtime
node_subscription_http -->|"requests data"| node_subscription_service
node_subscription_http -->|"serves Clash"| node_clash_output
node_subscription_service -->|"reads"| node_database
node_subscriber -->|"requests"| node_subscription_http
node_xray_core -.->|"runs"| node_external_proxy

click node_frontend "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/index/IndexPage.tsx"
click node_client_ui "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/clients/ClientsPage.tsx"
click node_inbound_ui "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/inbounds/InboundsPage.tsx"
click node_xray_ui "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/xray/routing/useRoutingColumns.tsx"
click node_node_ui "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/nodes/NodesPage.tsx"
click node_settings_ui "https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/settings/SettingsPage.tsx"
click node_api_controller "https://github.com/mhsanaei/3x-ui/blob/main/internal/web/controller/server.go"
click node_panel_service "https://github.com/mhsanaei/3x-ui/blob/main/internal/web/service/server.go"
click node_web_entry "https://github.com/mhsanaei/3x-ui/blob/main/main.go"
click node_xray_core "https://github.com/mhsanaei/3x-ui/blob/main/internal/web/service/server.go"
click node_amnezia_runtime "https://github.com/mhsanaei/3x-ui/blob/main/internal/amneziawgnet/manager.go"
click node_tuic_runtime "https://github.com/mhsanaei/3x-ui/blob/main/internal/tuic/server.go"
click node_mtproto_runtime "https://github.com/mhsanaei/3x-ui/blob/main/internal/mtproto/manager.go"
click node_subscription_http "https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/controller.go"
click node_subscription_service "https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/service.go"
click node_clash_output "https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/clash_service.go"
click node_database "https://github.com/mhsanaei/3x-ui/blob/main/internal/database/db.go"
click node_event_bus "https://github.com/mhsanaei/3x-ui/blob/main/internal/eventbus/bus.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_frontend,node_client_ui,node_inbound_ui,node_xray_ui,node_node_ui,node_settings_ui,node_subscriber toneBlue
class node_api_controller,node_panel_service,node_web_entry toneAmber
class node_xray_core,node_amnezia_runtime,node_tuic_runtime,node_mtproto_runtime toneMint
class node_subscription_http,node_subscription_service,node_clash_output toneRose
class node_database,node_event_bus,node_operator,node_external_proxy toneIndigo
```

## Components

### Operator interface

- [Management UI](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/index/IndexPage.tsx): `frontend/src/pages/index/IndexPage.tsx`
- [Client management](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/clients/ClientsPage.tsx): `frontend/src/pages/clients/ClientsPage.tsx`
- [Inbound configuration](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/inbounds/InboundsPage.tsx): `frontend/src/pages/inbounds/InboundsPage.tsx`
- [Routing and outbounds](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/xray/routing/useRoutingColumns.tsx): `frontend/src/pages/xray/routing/useRoutingColumns.tsx`
- [Node management](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/nodes/NodesPage.tsx): `frontend/src/pages/nodes/NodesPage.tsx`
- [Panel settings](https://github.com/mhsanaei/3x-ui/blob/main/frontend/src/pages/settings/SettingsPage.tsx): `frontend/src/pages/settings/SettingsPage.tsx`

### Panel services

- [HTTP API](https://github.com/mhsanaei/3x-ui/blob/main/internal/web/controller/server.go): `internal/web/controller/server.go`
- [Panel operations](https://github.com/mhsanaei/3x-ui/blob/main/internal/web/service/server.go): `internal/web/service/server.go`
- [Application startup](https://github.com/mhsanaei/3x-ui/blob/main/main.go): `main.go`

### Proxy runtime

- [Xray management](https://github.com/mhsanaei/3x-ui/blob/main/internal/web/service/server.go): `internal/web/service/server.go`
- [AmneziaWG runtime](https://github.com/mhsanaei/3x-ui/blob/main/internal/amneziawgnet/manager.go): `internal/amneziawgnet/manager.go`
- [TUIC server](https://github.com/mhsanaei/3x-ui/blob/main/internal/tuic/server.go): `internal/tuic/server.go`
- [MTProto manager](https://github.com/mhsanaei/3x-ui/blob/main/internal/mtproto/manager.go): `internal/mtproto/manager.go`

### Subscription delivery

- [Subscription endpoints](https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/controller.go): `internal/sub/controller.go`
- [Subscription generation](https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/service.go): `internal/sub/service.go`
- [Clash output](https://github.com/mhsanaei/3x-ui/blob/main/internal/sub/clash_service.go): `internal/sub/clash_service.go`

### Persistence and events

- [SQLite or PostgreSQL](https://github.com/mhsanaei/3x-ui/blob/main/internal/database/db.go): `internal/database/db.go`
- [Event bus](https://github.com/mhsanaei/3x-ui/blob/main/internal/eventbus/bus.go): `internal/eventbus/bus.go`

### Other components

- **Panel operator**
- **Subscription client**
- **Xray-core**

## Connections

- Panel operator → Management UI: manages (evidence: `README.md`)
- Management UI → Client management: opens
- Management UI → Inbound configuration: opens
- Management UI → Routing and outbounds: opens
- Management UI → Node management: opens
- Management UI → Panel settings: opens
- Application startup → Panel operations: starts (evidence: `main.go`)
- Application startup → Subscription endpoints: starts (evidence: `main.go`)
- HTTP API → Panel operations: delegates (evidence: `internal/web/controller/server.go`)
- Panel operations → SQLite or PostgreSQL: reads and writes (evidence: `internal/web/service/server.go`)
- Panel operations → Xray management: manages (evidence: `internal/web/service/server.go`)
- Panel operations → AmneziaWG runtime: configures (evidence: `internal/web/service/server.go`)
- Panel operations → TUIC server: configures
- Panel operations → MTProto manager: configures
- Subscription endpoints → Subscription generation: requests data (evidence: `internal/sub/controller.go`)
- Subscription endpoints → Clash output: serves Clash (evidence: `internal/sub/controller.go`)
- Subscription generation → SQLite or PostgreSQL: reads (evidence: `internal/sub/service.go`)
- Subscription client → Subscription endpoints: requests (evidence: `README.md`)
- Xray management → Xray-core: runs
