# deposist/s-ui-rus-inst architecture

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

- Interactive diagram: https://gitdiagram.com/deposist/s-ui-rus-inst
- Repository: https://github.com/deposist/s-ui-rus-inst

## Overview

1. This repository is a single Go-based control plane for Sing-Box. It combines a web admin panel, a subscription service, local persistence, and the runtime logic needed to create and manage Sing-Box configs and registrations. The frontend is a separate Vue 3 app built into the backend as static assets.

2. The main runtime entrypoints are `main.go`, `app/app.go`, and `core/main.go`. `cmd/` contains the CLI/admin tooling and versioned database migration entrypoints, while `install.sh`, `s-ui.sh`, systemd units, Docker files, and Windows scripts handle deployment rather than product logic.

3. The HTTP surface is split into two user-facing boundaries: the panel/API and the subscription endpoint. `api/` holds request handlers, session handling, and rate limiting for the admin UI; `sub/` handles subscription generation and export formats. The README’s default paths map to this split: `/app/` for the panel and `/sub/` for subscriptions.

4. The backend is layered around a service façade in `service/`. Those packages model the domain objects the panel edits: users/clients, settings, inbounds, outbounds, endpoints, TLS, statistics, WARP, and server/panel configuration. This is the layer that translates HTTP requests into persisted state and Sing-Box-facing configuration.

5. The core Sing-Box orchestration lives in `core/`. It contains endpoint registration, outbound checks, connection tracking, and statistics aggregation. The `register_*` files show platform/feature-specific registration strategies, including naive and Tailscale variants, with stub files for builds where those integrations are unavailable.

6. Persistence is centered in `database/`. `database/db.go` and `database/model/` define the stored schema for inbounds, outbounds, endpoints, services, and other panel state. `database/adapt.go` and the `cmd/migration/` package handle schema evolution and legacy database upgrades, while `database/backup.go` manages export/import and restore workflows.

7. The panel has a scheduling subsystem in `cronjob/` for recurring maintenance tasks. These jobs include stats collection, cleanup, depletion checks, core checks, and WAL checkpointing, which indicates the app keeps both live operational state and historical usage metrics.

8. Subscription generation and serialization are factored out into `sub/` and `util/`. The `util/` package contains helpers for base64, link generation, JSON conversion, and subscription metadata; `sub/` turns stored service/topology data into consumable subscription responses such as link, JSON, and Clash-compatible outputs.

9. The frontend is a fairly large Vue/Vite application under `frontend/`, organized by views, layouts, modal dialogs, protocol-specific editors, and shared components. It talks to the backend through `frontend/src/plugins/api.ts`, with local state in the store and locale files for multi-language UI. The backend serves the built frontend from `web/`.

10. Security and request-boundary concerns are explicit parts of the architecture. `api/rateLimit.go`, `api/session.go`, and middleware like `middleware/domainValidator.go` protect the admin surface; the README also documents trusted-proxy handling and subscription URL validation. That means client IP, login, and external fetch behavior are intentionally gated before data reaches the service layer.

11. `network/` abstracts listener behavior, including auto-HTTPS and bind/listen handling. This is the transport boundary between the panel/subscription HTTP servers and the host network, and it is also where listen-address resilience and TLS behavior are enforced.

12. `config/`, `logger/`, and `util/common/` provide cross-cutting infrastructure: versioning/name metadata, structured logging, and small shared utilities such as password and random helpers. These are support layers used by both the API/service code and the maintenance/migration code.

13. The project is designed for multiple deployment modes but the architecture stays the same: one long-running backend process, optional Sing-Box binary managed by that process, a browser-based admin SPA, and persistent state in a local DB directory. Docker, systemd, and Windows packaging are operational wrappers around that same core split.

Main entry points: [`app/app.go`](https://github.com/deposist/s-ui-rus-inst/blob/beta/app/app.go) (App boot), [`service/panel.go`](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/panel.go) (Service façade), [`api/apiHandler.go`](https://github.com/deposist/s-ui-rus-inst/blob/beta/api/apiHandler.go) (Panel API), [`core/main.go`](https://github.com/deposist/s-ui-rus-inst/blob/beta/core/main.go) (Core runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("main<br/>go entrypoint<br/>[main.go]"))
  node_app_boot["App boot<br/>go bootstrap<br/>[app.go]"]
  node_api_http["Panel API<br/>http handlers<br/>[apiHandler.go]"]
  node_api_auth["Session guard<br/>auth middleware<br/>[session.go]"]
  node_api_limit["Rate limit<br/>throttle<br/>[rateLimit.go]"]
  node_sub_http["Sub endpoint<br/>http handlers<br/>[subHandler.go]"]
end

subgraph group_domain["Domain"]
  node_sub_pipe["Sub pipeline<br/>export service<br/>[subService.go]"]
  node_svc_fa["Service façade<br/>domain façade<br/>[panel.go]"]
  node_svc_inbounds["Inbounds<br/>domain service<br/>[inbounds.go]"]
  node_svc_outbounds["Outbounds<br/>domain service<br/>[outbounds.go]"]
  node_svc_users["Users<br/>domain service<br/>[user.go]"]
  node_svc_stats["Stats<br/>metrics service<br/>[stats.go]"]
  node_core_main["Core runtime<br/>sing-box orchestration<br/>[main.go]"]
  node_core_regs["Registrations<br/>registration logic<br/>[register.go]"]
  node_core_track["Tracking<br/>connection/statistics<br/>[tracker_conn.go]"]
end

subgraph group_data["Data"]
  node_db_main[("Database<br/>persistence layer<br/>[db.go]")]
  node_db_backup["Backup<br/>restore/export<br/>[backup.go]"]
  node_cron_main(("Scheduler<br/>cron jobs<br/>[cronJob.go]"))
end

subgraph group_ui["UI"]
  node_frontend_app["Admin SPA<br/>vue app<br/>[main.ts]"]
  node_web_static["Static web<br/>asset server<br/>[web.go]"]
end

subgraph group_support["Support"]
  node_net_listen["Network I/O<br/>listener abstraction<br/>[listen.go]"]
  node_mw_domain["Domain guard<br/>request middleware<br/>[domainValidator.go]"]
  node_cfg["Config<br/>[config.go]"]
  node_log["Logger<br/>logging<br/>[logger.go]"]
end

node_main -->|"starts"| node_app_boot
node_app_boot -->|"hosts"| node_api_http
node_app_boot -->|"hosts"| node_sub_http
node_app_boot -->|"runs"| node_core_main
node_app_boot -->|"schedules"| node_cron_main
node_app_boot -->|"binds"| node_net_listen
node_app_boot -->|"serves"| node_web_static
node_api_http -->|"guards"| node_api_auth
node_api_http -->|"throttles"| node_api_limit
node_api_http -->|"mutates"| node_svc_fa
node_sub_http -->|"builds"| node_sub_pipe
node_sub_pipe -->|"reads"| node_svc_fa
node_svc_fa -->|"coordinates"| node_svc_inbounds
node_svc_fa -->|"coordinates"| node_svc_outbounds
node_svc_fa -->|"coordinates"| node_svc_users
node_svc_fa -->|"coordinates"| node_svc_stats
node_svc_fa -->|"persists"| node_db_main
node_svc_fa -->|"syncs"| node_core_main
node_core_main -->|"registers"| node_core_regs
node_core_main -->|"tracks"| node_core_track
node_core_main -->|"loads"| node_db_main
node_db_main -->|"exports"| node_db_backup
node_db_main -->|"maintains"| node_cron_main
node_cron_main -->|"collects"| node_svc_stats
node_net_listen -->|"enforces"| node_mw_domain
node_app_boot -->|"configures"| node_cfg
node_app_boot -->|"logs"| node_log
node_frontend_app -->|"calls"| node_api_http
node_frontend_app -->|"uses"| node_sub_http
node_web_static -->|"serves"| node_frontend_app

click node_main "https://github.com/deposist/s-ui-rus-inst/blob/beta/main.go"
click node_app_boot "https://github.com/deposist/s-ui-rus-inst/blob/beta/app/app.go"
click node_api_http "https://github.com/deposist/s-ui-rus-inst/blob/beta/api/apiHandler.go"
click node_api_auth "https://github.com/deposist/s-ui-rus-inst/blob/beta/api/session.go"
click node_api_limit "https://github.com/deposist/s-ui-rus-inst/blob/beta/api/rateLimit.go"
click node_sub_http "https://github.com/deposist/s-ui-rus-inst/blob/beta/sub/subHandler.go"
click node_sub_pipe "https://github.com/deposist/s-ui-rus-inst/blob/beta/sub/subService.go"
click node_svc_fa "https://github.com/deposist/s-ui-rus-inst/blob/beta/service/panel.go"
click node_svc_inbounds "https://github.com/deposist/s-ui-rus-inst/blob/beta/service/inbounds.go"
click node_svc_outbounds "https://github.com/deposist/s-ui-rus-inst/blob/beta/service/outbounds.go"
click node_svc_users "https://github.com/deposist/s-ui-rus-inst/blob/beta/service/user.go"
click node_svc_stats "https://github.com/deposist/s-ui-rus-inst/blob/beta/service/stats.go"
click node_core_main "https://github.com/deposist/s-ui-rus-inst/blob/beta/core/main.go"
click node_core_regs "https://github.com/deposist/s-ui-rus-inst/blob/beta/core/register.go"
click node_core_track "https://github.com/deposist/s-ui-rus-inst/blob/beta/core/tracker_conn.go"
click node_db_main "https://github.com/deposist/s-ui-rus-inst/blob/beta/database/db.go"
click node_db_backup "https://github.com/deposist/s-ui-rus-inst/blob/beta/database/backup.go"
click node_cron_main "https://github.com/deposist/s-ui-rus-inst/blob/beta/cronjob/cronJob.go"
click node_net_listen "https://github.com/deposist/s-ui-rus-inst/blob/beta/network/listen.go"
click node_mw_domain "https://github.com/deposist/s-ui-rus-inst/blob/beta/middleware/domainValidator.go"
click node_cfg "https://github.com/deposist/s-ui-rus-inst/blob/beta/config/config.go"
click node_log "https://github.com/deposist/s-ui-rus-inst/blob/beta/logger/logger.go"
click node_frontend_app "https://github.com/deposist/s-ui-rus-inst/blob/beta/frontend/src/main.ts"
click node_web_static "https://github.com/deposist/s-ui-rus-inst/blob/beta/web/web.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_main,node_app_boot,node_api_http,node_api_auth,node_api_limit,node_sub_http toneBlue
class node_sub_pipe,node_svc_fa,node_svc_inbounds,node_svc_outbounds,node_svc_users,node_svc_stats,node_core_main,node_core_regs,node_core_track toneAmber
class node_db_main,node_db_backup,node_cron_main toneMint
class node_frontend_app,node_web_static toneRose
class node_net_listen,node_mw_domain,node_cfg,node_log toneIndigo
```

## Components

### Runtime

Long-running backend entrypoints and request-serving boundaries

- [main](https://github.com/deposist/s-ui-rus-inst/blob/beta/main.go): go entrypoint · Top-level process bootstrap · `main.go`
- [App boot](https://github.com/deposist/s-ui-rus-inst/blob/beta/app/app.go): go bootstrap · Wires the backend runtime together · `app/app.go`
- [Panel API](https://github.com/deposist/s-ui-rus-inst/blob/beta/api/apiHandler.go): http handlers · Admin panel request surface · `api/apiHandler.go`
- [Session guard](https://github.com/deposist/s-ui-rus-inst/blob/beta/api/session.go): auth middleware · Login/session and boundary checks · `api/session.go`
- [Rate limit](https://github.com/deposist/s-ui-rus-inst/blob/beta/api/rateLimit.go): throttle · Protects the admin API from abuse · `api/rateLimit.go`
- [Sub endpoint](https://github.com/deposist/s-ui-rus-inst/blob/beta/sub/subHandler.go): http handlers · Subscription request surface · `sub/subHandler.go`

### Domain

Service façade and Sing-Box orchestration

- [Sub pipeline](https://github.com/deposist/s-ui-rus-inst/blob/beta/sub/subService.go): export service · Builds subscription responses and formats · `sub/subService.go`
- [Service façade](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/panel.go): domain façade · Coordinates panel edits into persisted state · `service/panel.go`
- [Inbounds](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/inbounds.go): domain service · Inbound configuration management · `service/inbounds.go`
- [Outbounds](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/outbounds.go): domain service · Outbound configuration management · `service/outbounds.go`
- [Users](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/user.go): domain service · Client and user lifecycle · `service/user.go`
- [Stats](https://github.com/deposist/s-ui-rus-inst/blob/beta/service/stats.go): metrics service · Usage and operational counters · `service/stats.go`
- [Core runtime](https://github.com/deposist/s-ui-rus-inst/blob/beta/core/main.go): sing-box orchestration · Registers endpoints and manages runtime state · `core/main.go`
- [Registrations](https://github.com/deposist/s-ui-rus-inst/blob/beta/core/register.go): registration logic · Feature-specific endpoint registration strategies · `core/register.go`
- [Tracking](https://github.com/deposist/s-ui-rus-inst/blob/beta/core/tracker_conn.go): connection/statistics · Connection tracking and statistics aggregation · `core/tracker_conn.go`

### Data

Local persistence, migrations, and backup

- [Database](https://github.com/deposist/s-ui-rus-inst/blob/beta/database/db.go): persistence layer · Primary local storage and schema access · `database/db.go`
- [Backup](https://github.com/deposist/s-ui-rus-inst/blob/beta/database/backup.go): restore/export · Backup, import, and restore workflows · `database/backup.go`
- [Scheduler](https://github.com/deposist/s-ui-rus-inst/blob/beta/cronjob/cronJob.go): cron jobs · Recurring maintenance and operational jobs · `cronjob/cronJob.go`

### UI

Vue admin panel and static asset delivery

- [Admin SPA](https://github.com/deposist/s-ui-rus-inst/blob/beta/frontend/src/main.ts): vue app · Browser-based admin interface built from Vue/Vite · `frontend/src/main.ts`
- [Static web](https://github.com/deposist/s-ui-rus-inst/blob/beta/web/web.go): asset server · Serves the built frontend assets · `web/web.go`

### Support

Cross-cutting infrastructure and transport

- [Network I/O](https://github.com/deposist/s-ui-rus-inst/blob/beta/network/listen.go): listener abstraction · Bind/listen handling and auto-HTTPS transport · `network/listen.go`
- [Domain guard](https://github.com/deposist/s-ui-rus-inst/blob/beta/middleware/domainValidator.go): request middleware · Validates request boundaries and trusted domains · `middleware/domainValidator.go`
- [Config](https://github.com/deposist/s-ui-rus-inst/blob/beta/config/config.go): runtime config · Versioning and name metadata · `config/config.go`
- [Logger](https://github.com/deposist/s-ui-rus-inst/blob/beta/logger/logger.go): logging · Structured application logging · `logger/logger.go`

## Connections

- main → App boot: starts · Main process boots the application runtime
- App boot → Panel API: hosts · Starts the panel/API surface
- App boot → Sub endpoint: hosts · Starts the subscription surface
- App boot → Core runtime: runs · Launches Sing-Box orchestration
- App boot → Scheduler: schedules · Enables recurring maintenance jobs
- App boot → Network I/O: binds · Uses transport/listener abstraction for server sockets
- App boot → Static web: serves · Exposes built frontend assets
- Panel API → Session guard: guards · Session handling protects admin requests
- Panel API → Rate limit: throttles · Rate limiting sits in front of the API
- Panel API → Service façade: mutates · API translates user actions into domain operations
- Sub endpoint → Sub pipeline: builds · Subscription handler delegates serialization and export
- Sub pipeline → Service façade: reads · Subscription generation uses stored service topology
- Service façade → Inbounds: coordinates · Facade delegates inbound edits
- Service façade → Outbounds: coordinates · Facade delegates outbound edits
- Service façade → Users: coordinates · Facade delegates client/user management
- Service façade → Stats: coordinates · Facade exposes operational stats
- Service façade → Database: persists · Domain state is stored locally
- Service façade → Core runtime: syncs · Service layer feeds Sing-Box runtime state
- Core runtime → Registrations: registers · Core uses registration strategies for endpoints
- Core runtime → Tracking: tracks · Core maintains connection and stats state
- Core runtime → Database: loads · Core reads persisted configuration and state
- Database → Backup: exports · Database supports backup and restore flows
- Database → Scheduler: maintains · Jobs clean up and checkpoint persisted state
- Scheduler → Stats: collects · Scheduled jobs gather and prune usage stats
- Network I/O → Domain guard: enforces · Listener/request boundary enforces trusted-domain rules
- App boot → Config: configures · Runtime setup is driven by application config
- App boot → Logger: logs · Bootstrap and services share structured logging
- Admin SPA → Panel API: calls · SPA talks to the backend API
- Admin SPA → Sub endpoint: uses · UI surfaces subscription-related features
- Static web → Admin SPA: serves · Backend serves the compiled admin SPA
