3x-ui/docs/panel-guide/01-overview-and-architecture.md

01. Overview and Architecture

What 3x-ui is

3x-ui is a control panel around Xray-core for:

• Inbound and client management
• Quota/expiry/statistics
• Advanced Xray config/routing editing
• Operational actions (restart, logs, backup/import/export)
• Optional subscription and Telegram integrations

Core runtime parts

• Web panel server: web/web.go
• Subscription server: sub/sub.go
• Xray integration service: web/service/xray.go
• Binary entrypoint: main.go

Data layer

Default storage is SQLite via GORM. Models include:

• User
• Inbound
• Setting
• OutboundTraffics
• InboundClientIps
• xray.ClientTraffic
• HistoryOfSeeders
• Custom extension: MasterClient, MasterClientInbound

Files:

• database/db.go
• database/model/model.go
• xray/client_traffic.go

Auth/session model

• Cookie session with secret from DB settings
• /panel/* requires login
• /panel/api/* also requires login
• Unauthorized API requests are intentionally hidden with 404 behavior

Files:

• web/controller/base.go
• web/controller/api.go
• web/session/session.go

Background jobs and periodic logic

Cron-based tasks include:

• Xray process health checks
• Traffic collection from Xray
• Auto disable/renew logic
• Client IP checks and cleanup
• Optional LDAP and Telegram jobs

Files:

• web/web.go
• web/job/*.go
• web/service/inbound.go

URL topology

UI:

• /
• /panel/
• /panel/inbounds
• /panel/clients (custom)
• /panel/settings
• /panel/xray

API:

• /panel/api/inbounds/*
• /panel/api/server/*
• /panel/api/clients/* (custom)
• /panel/xray/*
• /panel/setting/*

Subscription:

• Dynamic from settings (subPath, subJsonPath)