# zamibd/zpanel architecture

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

- Interactive diagram: https://gitdiagram.com/zamibd/zpanel
- Repository: https://github.com/zamibd/zpanel

## Overview

1. **Overall shape**
   ZPanel is a Go-based control plane for **Sing-Box** with a separate **Vue 3 + Vite frontend**. The backend exposes an admin API, serves the web panel, and also exposes a customer-facing subscription service. The system is organized around configuration management, runtime control of Sing-Box, persistence, and traffic/statistics tracking.

2. **Main runtime entry points**
   The top-level `main.go` and `app/` / `core/` packages form the server bootstrap path. `config/` holds application configuration and version/name metadata. `cmd/` contains CLI-oriented operations, including settings and migrations, suggesting the binary can initialize or upgrade stored state outside the normal web runtime.

3. **Backend request surfaces**
   There are three major HTTP-facing areas:
   - `web/` for serving the panel assets,
   - `api/` for the admin API,
   - `sub/` for subscription endpoints that produce link/json output for customers.
   
   The README’s default panel path and customer path map directly to these surfaces.

4. **Frontend subsystem**
   `frontend/` is a standalone SPA built with Vue, TypeScript, and Vuetify. It is organized by domain views such as Inbounds, Outbounds, Rules, Tls, Services, and Settings, plus modal editors for each object type. The UI talks to the backend through `frontend/src/plugins/api.ts`, so the frontend is a thin consumer of the backend API rather than a separate domain service.

5. **Domain/service layer**
   The `service/` package is the main application logic layer. It appears to group operations by domain object: clients, config, endpoints, inbounds, outbounds, services, settings, TLS, users, warp, and panel/server orchestration. This is the layer the API handlers likely call after auth/validation, keeping HTTP concerns separate from business rules.

6. **Sing-Box integration and core control**
   The `core/` package is the bridge to the underlying proxy engine. Files like `register.go`, `register_gvisor.go`, and `register_nogvisor.go` suggest pluggable runtime registration depending on whether gVisor support is available. `core/endpoint.go`, `core/box.go`, `core/main.go`, and tracker files indicate this layer manages the Sing-Box process/runtime, endpoints, and live connection/statistics reporting.

7. **Persistence and models**
   The `database/` package contains DB access plus structured models for endpoints, inbounds, outbounds, and services. This is the system-of-record for panel state. `database/backup.go` indicates built-in backup/restore support, and `cmd/migration/` shows schema or data migrations are first-class parts of the architecture.

8. **Traffic and usage observability**
   Traffic tracking is split across `core/tracker_conn.go`, `core/tracker_stats.go`, `service/stats.go`, and `cronjob/`. The panel is not just a configuration UI; it continuously observes live clients/inbounds/outbounds and aggregates usage into visible stats. The frontend has dedicated tiles and history components for these metrics.

9. **Background maintenance**
   `cronjob/` contains scheduled jobs such as core checking, stats collection, stats deletion, and quota depletion. This indicates a periodic maintenance loop running alongside the API server, responsible for keeping counts accurate and enforcing time/traffic limits on clients.

10. **Subscription generation subsystem**
   The `sub/` package generates customer subscription artifacts in multiple formats: link-based, JSON-based, Clash-oriented, and subscription service handlers. `util/` includes helpers such as link encoding, base64, and JSON conversion that support this export pipeline. This is a key boundary: internal panel configuration is transformed into externally consumable subscription outputs.

11. **Networking and TLS handling**
   `network/auto_https_*` and `middleware/domainValidator.go` suggest the backend can manage HTTPS/TLS concerns for the panel/subscription endpoints and validate host/domain usage. This aligns with the README’s support for self-provided domain + SSL certificate and secure access to both admin and customer endpoints.

12. **API/auth/session boundary**
   The `api/` package includes handlers, API service code, session handling, and versioned endpoints (`apiV2Handler.go`). This suggests request authentication/session state is centralized before delegating to services. The presence of `middleware` implies cross-cutting validation is applied at the HTTP boundary rather than inside domain services.

13. **Deployment and packaging**
   The repo includes `Dockerfile`, `docker-compose.yml`, `install.sh`, `build.sh`, and systemd service files (`ZPanel.service`, `ZPanel.sh`). This is designed for self-hosted deployment, with the backend and frontend packaged together into a panel service, and Sing-Box integrated as an external/runtime dependency controlled by the panel.

14. **Diagramming guidance**
   For an architecture diagram, the most important flows are:
   - Browser/UI → `web/` static assets → `api/` / `sub/`
   - `api/` → `service/` → `database/` and `core/`
   - `cronjob/` → `service/` / `core/` / `database/`
   - `sub/` → `util/` transformation helpers → subscription outputs
   - `core/` → Sing-Box runtime / trackers / connection stats
   
   The cleanest boundaries are: presentation, API/auth, domain services, Sing-Box runtime control, persistence, subscription export, and background jobs.

Main entry points: [`api/apiHandler.go`](https://github.com/zamibd/zpanel/blob/main/api/apiHandler.go) (Admin API), [`sub/sub.go`](https://github.com/zamibd/zpanel/blob/main/sub/sub.go) (Sub export), [`database/db.go`](https://github.com/zamibd/zpanel/blob/main/database/db.go) (Database), [`app/app.go`](https://github.com/zamibd/zpanel/blob/main/app/app.go) (App bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend_entry["Backend entrypoints"]
  node_main_go(("Main<br/>go entrypoint<br/>[main.go]"))
  node_app_app_go["App bootstrap<br/>app wiring<br/>[app.go]"]
  node_config_go["Config<br/>settings<br/>[config.go]"]
  node_cmd_main_go["CLI entry<br/>admin CLI<br/>[cmd.go]"]
  node_cmd_migration_main_go["Migrations<br/>schema upgrade<br/>[main.go]"]
end

subgraph group_backend_http["HTTP surfaces"]
  node_web_web_go["Web host<br/>static web<br/>[web.go]"]
  node_api_api_handler_go["Admin API<br/>http handlers<br/>[apiHandler.go]"]
  node_api_api_v2_handler_go["API v2<br/>versioned API<br/>[apiV2Handler.go]"]
  node_api_session_go["Session<br/>auth state<br/>[session.go]"]
  node_sub_sub_handler_go["Sub handler<br/>customer HTTP<br/>[subHandler.go]"]
end

subgraph group_backend_domain["Domain services"]
  node_service_panel_go["Panel svc<br/>orchestration<br/>[panel.go]"]
  node_service_config_go["Config svc<br/>domain logic<br/>[config.go]"]
  node_service_inbounds_go["Inbounds<br/>domain logic<br/>[inbounds.go]"]
  node_service_outbounds_go["Outbounds<br/>domain logic<br/>[outbounds.go]"]
  node_service_endpoints_go["Endpoints<br/>domain logic<br/>[endpoints.go]"]
  node_service_stats_go["Stats svc<br/>metrics logic<br/>[stats.go]"]
  node_service_user_go["Users<br/>domain logic<br/>[user.go]"]
end

subgraph group_backend_runtime["Runtime and data"]
  node_database_db_go[("Database<br/>persistence<br/>[db.go]")]
  node_database_backup_go["Backup<br/>persistence ops<br/>[backup.go]"]
  node_core_main_go["Core runtime<br/>sing-box control<br/>[main.go]"]
  node_core_box_go["Box<br/>runtime control<br/>[box.go]"]
  node_core_tracker_stats_go["Tracker stats<br/>telemetry<br/>[tracker_stats.go]"]
  node_sub_sub_go["Sub export<br/>subscription pipeline<br/>[sub.go]"]
  node_sub_link_service_go["Link export<br/>format adapter<br/>[linkService.go]"]
  node_sub_json_service_go["JSON export<br/>format adapter<br/>[jsonService.go]"]
  node_sub_clash_service_go["Clash export<br/>format adapter<br/>[clashService.go]"]
end

subgraph group_backend_jobs["Background jobs"]
  node_cronjob_cronjob_go["Cron jobs<br/>scheduler<br/>[cronJob.go]"]
  node_cronjob_stats_job_go["Stats job<br/>scheduled task<br/>[statsJob.go]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app_vue["Panel UI<br/>vue spa<br/>[App.vue]"]
  node_frontend_api_ts["API client<br/>frontend client<br/>[api.ts]"]
  node_frontend_views["Views<br/>ui screens<br/>[Home.vue]"]
end

node_main_go -->|"bootstraps"| node_app_app_go
node_main_go -->|"loads"| node_config_go
node_main_go -.->|"invokes CLI"| node_cmd_main_go
node_cmd_main_go -->|"runs"| node_cmd_migration_main_go
node_app_app_go -->|"serves UI"| node_web_web_go
node_app_app_go -->|"mounts"| node_api_api_handler_go
node_app_app_go -->|"mounts"| node_sub_sub_handler_go
node_api_api_handler_go -->|"authenticates"| node_api_session_go
node_api_api_handler_go -->|"routes"| node_api_api_v2_handler_go
node_api_api_handler_go -->|"calls"| node_service_panel_go
node_api_api_handler_go -->|"calls"| node_service_inbounds_go
node_api_api_handler_go -->|"calls"| node_service_outbounds_go
node_api_api_handler_go -->|"calls"| node_service_endpoints_go
node_api_api_handler_go -->|"calls"| node_service_user_go
node_service_panel_go -->|"controls runtime"| node_core_main_go
node_service_config_go -->|"reads/writes"| node_database_db_go
node_service_inbounds_go -->|"reads/writes"| node_database_db_go
node_service_outbounds_go -->|"reads/writes"| node_database_db_go
node_service_endpoints_go -->|"reads/writes"| node_database_db_go
node_service_stats_go -->|"collects"| node_core_tracker_stats_go
node_core_main_go -->|"runs"| node_core_box_go
node_core_main_go -->|"loads state"| node_database_db_go
node_core_main_go -->|"emits stats"| node_core_tracker_stats_go
node_cronjob_cronjob_go -->|"schedules"| node_cronjob_stats_job_go
node_cronjob_stats_job_go -->|"updates"| node_service_stats_go
node_cronjob_stats_job_go -->|"maintains"| node_database_db_go
node_sub_sub_handler_go -->|"delegates"| node_sub_sub_go
node_sub_sub_go -->|"formats"| node_sub_link_service_go
node_sub_sub_go -->|"formats"| node_sub_json_service_go
node_sub_sub_go -->|"formats"| node_sub_clash_service_go
node_sub_sub_go -->|"reads config"| node_service_config_go
node_sub_sub_go -->|"reads state"| node_database_db_go
node_frontend_app_vue -->|"calls"| node_frontend_api_ts
node_frontend_api_ts -->|"requests"| node_api_api_handler_go
node_frontend_views -->|"consumes"| node_frontend_api_ts
node_frontend_views -->|"renders in"| node_frontend_app_vue

click node_main_go "https://github.com/zamibd/zpanel/blob/main/main.go"
click node_app_app_go "https://github.com/zamibd/zpanel/blob/main/app/app.go"
click node_config_go "https://github.com/zamibd/zpanel/blob/main/config/config.go"
click node_cmd_main_go "https://github.com/zamibd/zpanel/blob/main/cmd/cmd.go"
click node_cmd_migration_main_go "https://github.com/zamibd/zpanel/blob/main/cmd/migration/main.go"
click node_web_web_go "https://github.com/zamibd/zpanel/blob/main/web/web.go"
click node_api_api_handler_go "https://github.com/zamibd/zpanel/blob/main/api/apiHandler.go"
click node_api_api_v2_handler_go "https://github.com/zamibd/zpanel/blob/main/api/apiV2Handler.go"
click node_api_session_go "https://github.com/zamibd/zpanel/blob/main/api/session.go"
click node_sub_sub_handler_go "https://github.com/zamibd/zpanel/blob/main/sub/subHandler.go"
click node_service_panel_go "https://github.com/zamibd/zpanel/blob/main/service/panel.go"
click node_service_config_go "https://github.com/zamibd/zpanel/blob/main/service/config.go"
click node_service_inbounds_go "https://github.com/zamibd/zpanel/blob/main/service/inbounds.go"
click node_service_outbounds_go "https://github.com/zamibd/zpanel/blob/main/service/outbounds.go"
click node_service_endpoints_go "https://github.com/zamibd/zpanel/blob/main/service/endpoints.go"
click node_service_stats_go "https://github.com/zamibd/zpanel/blob/main/service/stats.go"
click node_service_user_go "https://github.com/zamibd/zpanel/blob/main/service/user.go"
click node_database_db_go "https://github.com/zamibd/zpanel/blob/main/database/db.go"
click node_database_backup_go "https://github.com/zamibd/zpanel/blob/main/database/backup.go"
click node_core_main_go "https://github.com/zamibd/zpanel/blob/main/core/main.go"
click node_core_box_go "https://github.com/zamibd/zpanel/blob/main/core/box.go"
click node_core_tracker_stats_go "https://github.com/zamibd/zpanel/blob/main/core/tracker_stats.go"
click node_cronjob_cronjob_go "https://github.com/zamibd/zpanel/blob/main/cronjob/cronJob.go"
click node_cronjob_stats_job_go "https://github.com/zamibd/zpanel/blob/main/cronjob/statsJob.go"
click node_sub_sub_go "https://github.com/zamibd/zpanel/blob/main/sub/sub.go"
click node_sub_link_service_go "https://github.com/zamibd/zpanel/blob/main/sub/linkService.go"
click node_sub_json_service_go "https://github.com/zamibd/zpanel/blob/main/sub/jsonService.go"
click node_sub_clash_service_go "https://github.com/zamibd/zpanel/blob/main/sub/clashService.go"
click node_frontend_app_vue "https://github.com/zamibd/zpanel/blob/main/frontend/src/App.vue"
click node_frontend_api_ts "https://github.com/zamibd/zpanel/blob/main/frontend/src/plugins/api.ts"
click node_frontend_views "https://github.com/zamibd/zpanel/blob/main/frontend/src/views/Home.vue"

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_main_go,node_app_app_go,node_config_go,node_cmd_main_go,node_cmd_migration_main_go toneBlue
class node_web_web_go,node_api_api_handler_go,node_api_api_v2_handler_go,node_api_session_go,node_sub_sub_handler_go toneAmber
class node_service_panel_go,node_service_config_go,node_service_inbounds_go,node_service_outbounds_go,node_service_endpoints_go,node_service_stats_go,node_service_user_go toneMint
class node_database_db_go,node_database_backup_go,node_core_main_go,node_core_box_go,node_core_tracker_stats_go,node_sub_sub_go,node_sub_link_service_go,node_sub_json_service_go,node_sub_clash_service_go toneRose
class node_cronjob_cronjob_go,node_cronjob_stats_job_go toneIndigo
class node_frontend_app_vue,node_frontend_api_ts,node_frontend_views toneTeal
```

## Components

### Backend entrypoints

Process bootstrap, CLI, and config setup

- [Main](https://github.com/zamibd/zpanel/blob/main/main.go): go entrypoint · Top-level process start for the panel binary · `main.go`
- [App bootstrap](https://github.com/zamibd/zpanel/blob/main/app/app.go): app wiring · Initial application setup and server assembly · `app/app.go`
- [Config](https://github.com/zamibd/zpanel/blob/main/config/config.go): settings · App naming, versioning, and runtime configuration · `config/config.go`
- [CLI entry](https://github.com/zamibd/zpanel/blob/main/cmd/cmd.go): admin CLI · Command-line operations for setup and maintenance · `cmd/cmd.go`
- [Migrations](https://github.com/zamibd/zpanel/blob/main/cmd/migration/main.go): schema upgrade · Versioned database or state migration entrypoint · `cmd/migration/main.go`

### HTTP surfaces

Admin API, web hosting, and customer subscription endpoints

- [Web host](https://github.com/zamibd/zpanel/blob/main/web/web.go): static web · Serves the built panel assets · `web/web.go`
- [Admin API](https://github.com/zamibd/zpanel/blob/main/api/apiHandler.go): http handlers · Primary authenticated admin request handlers · `api/apiHandler.go`
- [API v2](https://github.com/zamibd/zpanel/blob/main/api/apiV2Handler.go): versioned API · Versioned admin endpoints · `api/apiV2Handler.go`
- [Session](https://github.com/zamibd/zpanel/blob/main/api/session.go): auth state · Session and login state management · `api/session.go`
- [Sub handler](https://github.com/zamibd/zpanel/blob/main/sub/subHandler.go): customer HTTP · Customer-facing subscription request handling · `sub/subHandler.go`

### Domain services

Application logic organized by panel domain

- [Panel svc](https://github.com/zamibd/zpanel/blob/main/service/panel.go): orchestration · High-level panel coordination and lifecycle logic · `service/panel.go`
- [Config svc](https://github.com/zamibd/zpanel/blob/main/service/config.go): domain logic · Configuration assembly and transformation services · `service/config.go`
- [Inbounds](https://github.com/zamibd/zpanel/blob/main/service/inbounds.go): domain logic · Inbound object operations and validation · `service/inbounds.go`
- [Outbounds](https://github.com/zamibd/zpanel/blob/main/service/outbounds.go): domain logic · Outbound object operations and validation · `service/outbounds.go`
- [Endpoints](https://github.com/zamibd/zpanel/blob/main/service/endpoints.go): domain logic · Endpoint lifecycle and panel exposure logic · `service/endpoints.go`
- [Stats svc](https://github.com/zamibd/zpanel/blob/main/service/stats.go): metrics logic · Usage aggregation and statistics queries · `service/stats.go`
- [Users](https://github.com/zamibd/zpanel/blob/main/service/user.go): domain logic · User and admin account operations · `service/user.go`

### Runtime and data

Sing-Box control, persistence, and telemetry

- [Database](https://github.com/zamibd/zpanel/blob/main/database/db.go): persistence · Storage access and system-of-record management · `database/db.go`
- [Backup](https://github.com/zamibd/zpanel/blob/main/database/backup.go): persistence ops · Backup and restore support for stored state · `database/backup.go`
- [Core runtime](https://github.com/zamibd/zpanel/blob/main/core/main.go): sing-box control · Bridge to the underlying Sing-Box process/runtime · `core/main.go`
- [Box](https://github.com/zamibd/zpanel/blob/main/core/box.go): runtime control · Sing-Box lifecycle and process control · `core/box.go`
- [Tracker stats](https://github.com/zamibd/zpanel/blob/main/core/tracker_stats.go): telemetry · Live connection and usage statistics collection · `core/tracker_stats.go`
- [Sub export](https://github.com/zamibd/zpanel/blob/main/sub/sub.go): subscription pipeline · Transforms panel data into external subscription artifacts · `sub/sub.go`
- [Link export](https://github.com/zamibd/zpanel/blob/main/sub/linkService.go): format adapter · Builds subscription links · `sub/linkService.go`
- [JSON export](https://github.com/zamibd/zpanel/blob/main/sub/jsonService.go): format adapter · Builds JSON subscription output · `sub/jsonService.go`
- [Clash export](https://github.com/zamibd/zpanel/blob/main/sub/clashService.go): format adapter · Builds Clash-oriented subscription output · `sub/clashService.go`

### Background jobs

Periodic maintenance and enforcement tasks

- [Cron jobs](https://github.com/zamibd/zpanel/blob/main/cronjob/cronJob.go): scheduler · Periodic job runner for maintenance tasks · `cronjob/cronJob.go`
- [Stats job](https://github.com/zamibd/zpanel/blob/main/cronjob/statsJob.go): scheduled task · Periodic stats collection and aggregation · `cronjob/statsJob.go`

### Frontend

Vue single-page panel UI

- [Panel UI](https://github.com/zamibd/zpanel/blob/main/frontend/src/App.vue): vue spa · Single-page administration interface · `frontend/src/App.vue`
- [API client](https://github.com/zamibd/zpanel/blob/main/frontend/src/plugins/api.ts): frontend client · Frontend API access layer · `frontend/src/plugins/api.ts`
- [Views](https://github.com/zamibd/zpanel/blob/main/frontend/src/views/Home.vue): ui screens · Main panel screens for admins and configuration · `frontend/src/views/Home.vue`

## Connections

- Main → App bootstrap: bootstraps · Process start wires the application
- Main → Config: loads · Reads app configuration and version metadata
- Main → CLI entry: invokes CLI · Supports administrative command-line entrypoints
- CLI entry → Migrations: runs · CLI can trigger migrations and setup tasks
- App bootstrap → Web host: serves UI · Hosts the static web panel
- App bootstrap → Admin API: mounts · Registers admin API handlers
- App bootstrap → Sub handler: mounts · Registers subscription endpoints
- Admin API → Session: authenticates · API requests rely on session state
- Admin API → API v2: routes · Dispatches versioned endpoint handlers
- Admin API → Panel svc: calls · Delegates business operations to services
- Admin API → Inbounds: calls · Manages inbound objects through service layer
- Admin API → Outbounds: calls · Manages outbound objects through service layer
- Admin API → Endpoints: calls · Manages endpoints through service layer
- Admin API → Users: calls · Admin/user operations flow through services
- Panel svc → Core runtime: controls runtime · Panel orchestration reaches Sing-Box control
- Config svc → Database: reads/writes · Configuration state is persisted
- Inbounds → Database: reads/writes · Inbound definitions are stored in the database
- Outbounds → Database: reads/writes · Outbound definitions are stored in the database
- Endpoints → Database: reads/writes · Endpoint state is persisted
- Stats svc → Tracker stats: collects · Stats service consumes live runtime telemetry
- Core runtime → Box: runs · Core layer manages the Sing-Box process
- Core runtime → Database: loads state · Runtime uses persisted configuration and models
- Core runtime → Tracker stats: emits stats · Runtime exposes live traffic and connection tracking
- Cron jobs → Stats job: schedules · Scheduler triggers periodic stats jobs
- Stats job → Stats svc: updates · Background jobs refresh aggregated statistics
- Stats job → Database: maintains · Periodic maintenance updates stored counters and quotas
- Sub handler → Sub export: delegates · Subscription HTTP layer uses export pipeline
- Sub export → Link export: formats · Generates link-based subscription output
- Sub export → JSON export: formats · Generates JSON subscription output
- Sub export → Clash export: formats · Generates Clash-compatible output
- Sub export → Config svc: reads config · Subscription output is derived from panel configuration
- Sub export → Database: reads state · Subscription exports depend on persisted objects
- Panel UI → API client: calls · UI uses the frontend API client
- API client → Admin API: requests · Frontend talks to the admin API
- Views → API client: consumes · Views load and mutate data through the API layer
- Views → Panel UI: renders in · Screens compose the main application shell