zamibd/zpanel

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.