# vaxilu/x-ui architecture

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

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

## Overview

##### Project type and purpose
- From the README and file structure, x-ui is a full-stack web panel (monolithic Go application) to manage the Xray proxy engine.
- Frontend: static Vue/Ant-Design/Element-UI assets under `web/assets`.
- Backend: Go HTTP server, MVC-style controllers/services, data access (SQLite via `database/db.go`), job schedulers, and Xray process management.
- It also bundles the Xray binaries (`bin/xray-*`), supports SSL cert issuance (via Cloudflare DNS API), and can run as a systemd service or in Docker.

##### File structure
- Top-level:
- `main.go`: application entrypoint
- `config/`: configuration loading
- `database/`: DB connection + model definitions
- `util/`: common helpers (error handling, JSON, reflection, syscalls)
- `logger/`: logging
- `web/`: MVC implementation –
– `web/controller/`: HTTP handlers
– `web/service/`: business logic
– `web/entity/` & `web/global/`: shared types/globals
– `web/html/`: HTML templates
– `web/assets/`: frontend dependencies and JS models
– `web/job/`: background jobs for stats, health checks
– `web/session/`: session management
– `web/network/`: TLS listener wrapper
- `xray/`: wrappers to start/stop Xray engine, traffic capture
- `v2ui/`: migration helpers from v2-ui
- Deployment: `Dockerfile`, `install.sh`, `x-ui.service`

##### Key points from README
- Multi-protocol support, multi-user, traffic monitoring, SSL automation.
- Installation via script, manual instructions or Docker.
- Uses Let’s Encrypt + Cloudflare DNS for certs.
- Data stored locally (likely SQLite under `/etc/x-ui/db/`).

a. Main components
1. User’s Browser (HTTPS)
2. Frontend Static Server (built-in Go HTTP serving `web/assets` + templates)
3. Go Backend
– HTTP Router → Controllers → Services
– DB Layer (SQLite or file-based DB)
– Job Scheduler (periodic jobs)
– Xray Manager (spawns Xray processes, reads/writes `bin/xray-*`)
– SSL Manager (invokes ACME via Cloudflare API)
4. Data Store (SQLite file)
5. Xray Engine processes (child processes)
6. External Services
– Cloudflare DNS API (for certs)
– Let’s Encrypt CA
– (Optional) Telegram Bot API
b. Relationships & data flows
- Browser → HTTPS → Go HTTP Server
- HTTP Server → Controller → Service → DB (read/write configs, users, traffic stats)
- Control commands → Xray Manager → spawn/kill Xray process
- Periodic jobs → gather Xray traffic logs → write stats to DB
- SSL Manager → Cloudflare DNS API ↔ Let’s Encrypt → certificates saved to filesystem
- Backend serves updated certs to frontend or rebinds HTTPS listener
- (Optional) Jobs push notifications via Telegram API
c. Architectural patterns
- Monolithic layered architecture
- MVC (Controllers → Services → Data Access)
- Embedded static assets
- Process-wrapper pattern for managing external Xray engine
- Job scheduling for background tasks
d. Key technologies/frameworks
- Language: Go
- Frontend: Vue.js, Ant-Design-Vue, Element-UI
- DataStore: SQLite (via Go’s database/sql)
- SSL: ACME (Let’s Encrypt) + Cloudflare DNS API
- Process control: Go `os/exec` for Xray
- Deployment: systemd, Docker

##### Detail
- Subcomponent (Controllers, Services, Jobs) if clarity is needed.
- Filesystem mounts for Docker or path locations for configs/db.
- Service lifecycle: install.sh → systemd → `x-ui` binary → loads config → serves UI & manages Xray.
- Don’t overload—focus on logical separation of UI, API, data, engine management, and external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser(["User Browser"]):::frontend
        Assets(["Static Assets\n(web/assets)"]):::frontend
        Templates(["HTML Templates\n(web/html)"]):::frontend
        Browser -->|"HTTPS Request"| Assets
        Browser -->|"HTTPS Request"| Templates
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        HTTPServer(["Go HTTP Server\n(main.go)"]):::backend
        Controllers(["HTTP Controllers\n(web/controller)"]):::backend
        Services(["Business Services\n(web/service)"]):::backend
        Entities(["Shared Entities\n(entity.go)"]):::backend
        Globals(["Global Variables\n(global.go)"]):::backend
        Session(["Session Management\n(session.go)"]):::backend
        Network(["TLS Listener\n(auto_https_listener.go)"]):::backend
        Config(["Configuration Loader\n(config.go)"]):::infrastructure
        Logger(["Logger Module\n(logger.go)"]):::infrastructure
        UtilCommon(["Util Helpers\n(util/common)"]):::infrastructure
        UtilJSON(["JSON Helpers\n(util/json_util/json.go)"]):::infrastructure
        UtilReflect(["Reflection Helpers\n(util/reflect_util/reflect.go)"]):::infrastructure
        UtilSys(["System Calls\n(util/sys)"]):::infrastructure
        DBConn(["DB Connection\n(db.go)"]):::infrastructure
        DBModels(["DB Models\n(model/model.go)"]):::infrastructure

        HTTPServer -->|"routes to"| Controllers
        Controllers -->|"calls"| Services
        Services -->|"reads/writes"| DBConn
        Services -->|"uses"| Entities
        Services -->|"uses"| Globals
        Services -->|"uses"| Session
        Services -->|"uses"| Network
        Services -->|"uses"| Logger
        Services -->|"uses"| Config
        Services -->|"uses"| UtilCommon
        Services -->|"uses"| UtilJSON
        Services -->|"uses"| UtilReflect
        Services -->|"uses"| UtilSys
        DBConn -->|"defines models"| DBModels
    end

    %% Xray Manager
    subgraph "Xray Engine Manager" 
        direction TB
        XrayProcessControl(["Process Control\n(xray/process.go)"]):::backend
        XrayInbound(["Inbound Config\n(xray/inbound.go)"]):::backend
        XrayTraffic(["Traffic Capture\n(xray/traffic.go)"]):::backend
        XrayConfig(["Xray Config\n(xray/config.go)"]):::backend

        Services -->|"manages"| XrayProcessControl
        XrayProcessControl --> XrayInbound
        XrayProcessControl --> XrayConfig
        XrayProcessControl --> XrayTraffic
    end

    %% Job Scheduler
    subgraph "Background Jobs"
        direction TB
        JobScheduler(["Job Scheduler\n(web/job)"]):::backend
        JobScheduler -->|"spawns reads"| XrayTraffic
        JobScheduler -->|"writes stats"| DBConn
    end

    %% SSL Manager
    subgraph "SSL Manager"
        direction TB
        SSLManager(["ACME Manager\n(Cloudflare API)"]):::backend
        SSLManager -->|"DNS Challenge"| Cloudflare
        SSLManager -->|"cert request"| LetsEncrypt
    end

    %% Data Store
    DBFile[(SQLite DB File)]:::datastore
    DBConn --> DBFile

    %% External Services
    Cloudflare(["Cloudflare DNS API"]):::external
    LetsEncrypt(["Let's Encrypt CA"]):::external
    Telegram(["Telegram Bot API"]):::external
    JobScheduler -->|"optional notifications"| Telegram

    %% Frontend to Backend
    Assets -->|"static serve"| HTTPServer
    Templates -->|"template serve"| HTTPServer

    %% Classes
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#154360;
    classDef backend fill:#D5F5E3,stroke:#145A32,color:#0B5345;
    classDef infrastructure fill:#FADBD8,stroke:#78281F,color:#641E16;
    classDef datastore fill:#FCF3CF,stroke:#7D6608,color:#7E5109;
    classDef external fill:#E5E7E9,stroke:#424949,color:#212F3D;

    %% Click Events
    click Assets "https://github.com/vaxilu/x-ui/tree/main/web/assets"
    click Templates "https://github.com/vaxilu/x-ui/tree/main/web/html"
    click Controllers "https://github.com/vaxilu/x-ui/tree/main/web/controller"
    click Services "https://github.com/vaxilu/x-ui/tree/main/web/service"
    click Entities "https://github.com/vaxilu/x-ui/blob/main/web/entity/entity.go"
    click Globals "https://github.com/vaxilu/x-ui/blob/main/web/global/global.go"
    click Session "https://github.com/vaxilu/x-ui/blob/main/web/session/session.go"
    click Network "https://github.com/vaxilu/x-ui/blob/main/web/network/auto_https_listener.go"
    click HTTPServer "https://github.com/vaxilu/x-ui/blob/main/main.go"
    click Config "https://github.com/vaxilu/x-ui/blob/main/config/config.go"
    click DBConn "https://github.com/vaxilu/x-ui/blob/main/database/db.go"
    click DBModels "https://github.com/vaxilu/x-ui/blob/main/database/model/model.go"
    click Logger "https://github.com/vaxilu/x-ui/blob/main/logger/logger.go"
    click UtilCommon "https://github.com/vaxilu/x-ui/tree/main/util/common"
    click UtilJSON "https://github.com/vaxilu/x-ui/blob/main/util/json_util/json.go"
    click UtilReflect "https://github.com/vaxilu/x-ui/blob/main/util/reflect_util/reflect.go"
    click UtilSys "https://github.com/vaxilu/x-ui/tree/main/util/sys"
    click XrayProcessControl "https://github.com/vaxilu/x-ui/blob/main/xray/process.go"
    click XrayInbound "https://github.com/vaxilu/x-ui/blob/main/xray/inbound.go"
    click XrayTraffic "https://github.com/vaxilu/x-ui/blob/main/xray/traffic.go"
    click XrayConfig "https://github.com/vaxilu/x-ui/blob/main/xray/config.go"
    click JobScheduler "https://github.com/vaxilu/x-ui/tree/main/web/job"
```
