# gui-for-cores/gui.for.singbox architecture

> Architecture diagram of the GitHub repository gui-for-cores/gui.for.singbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gui-for-cores/gui.for.singbox
- Repository: https://github.com/gui-for-cores/gui.for.singbox

## Overview

#### Purpose and Runtime
GUI.for.SingBox is a cross-platform desktop GUI for configuring and operating the Sing-box proxy core. It is built with Wails: a Go native host embeds a Vue frontend. The primary native entry point is `main.go`; application/window packaging is defined in `wails.json` and platform metadata under `build/`.

#### Desktop Host and Native Bridge
The Go `bridge` package exposes OS-facing capabilities to the frontend through generated Wails bindings. Its responsibilities include process execution, filesystem I/O, networking, MMDB handling, local server support, system proxy integration, and tray behavior.
- `bridge/bridge.go`
- `bridge/exec.go`
- `bridge/system_proxy.go`
- `bridge/tray.go`
- `frontend/src/bridge/wailsjs/go/bridge/App.js`

The frontend should use its typed bridge wrappers rather than invoke native APIs directly:
- `frontend/src/bridge/index.ts`
- `frontend/src/bridge/exec.ts`
- `frontend/src/bridge/io.ts`

#### Frontend Bootstrap and Application Shell
Vue starts at `frontend/src/main.ts`, mounts `frontend/src/App.vue`, and initializes lifecycle/bootstrap behavior before rendering the shared desktop shell. The shell owns navigation, title-bar behavior, splash state, and globally mounted modal/message overlays.
- `frontend/src/main.ts`
- `frontend/src/App.vue`
- `frontend/src/hooks/useAppBootstrap.ts`
- `frontend/src/components/_common/AppShell.vue`

#### Routing and Feature Domains
Client-side routes divide the app into operational domains: dashboard/control, profiles, subscriptions, rulesets, plugins, scheduled tasks, and settings.
- `frontend/src/router/routes.ts`
- `frontend/src/views/HomeView/index.vue`
- `frontend/src/views/ProfilesView/index.vue`
- `frontend/src/views/SettingsView/index.vue`

Profiles expose structured Sing-box configuration editing for inbounds, outbounds, DNS, routing, rules, rulesets, and mixin/script content:
- `frontend/src/views/ProfilesView/components/ProfileEditor.vue`
- `frontend/src/views/ProfilesView/components/DnsConfig.vue`
- `frontend/src/views/ProfilesView/components/RouteConfig.vue`

#### State, Persistence, and Configuration Flow
Pinia-style stores represent application settings, environment state, profiles, subscriptions, rulesets, plugins, task definitions, logs, and kernel API state. Views edit domain entities through these stores; persistence and native filesystem actions cross the frontend/native bridge boundary.
- `frontend/src/stores/app.ts`
- `frontend/src/stores/profiles.ts`
- `frontend/src/stores/kernelApi.ts`
- `frontend/src/stores/subscribes.ts`

Configuration-oriented views and stores are the main control plane for generating or selecting the Sing-box runtime configuration; they are distinct from live kernel interaction.

#### Sing-box Kernel Control and Live Observability
The frontend has a dedicated API layer for communicating with the running core, including request and WebSocket channels. The home dashboard consumes this control/telemetry surface for connections, traffic, groups, logs, and quick actions.
- `frontend/src/api/kernel.ts`
- `frontend/src/api/request.ts`
- `frontend/src/api/websocket.ts`
- `frontend/src/views/HomeView/components/ConnectionsController.vue`
- `frontend/src/views/HomeView/components/KernelLogs.vue`

Native process management is the boundary between UI/kernel control and the installed or managed Sing-box executable:
- `bridge/exec.go`
- `bridge/server.go`
- `frontend/src/bridge/server.ts`

#### External Dependencies and Delivery
Material runtimes are Go, Node.js/pnpm, Vue/Vite, and Wails. The app integrates with the operating system for system proxy and tray functionality, with Sing-box as the managed proxy kernel, and likely local/network endpoints through its kernel HTTP/WebSocket clients. Release and rolling-release automation are GitHub Actions workflows.
- `go.mod`
- `frontend/package.json`
- `.github/workflows/release.yml`
- `.github/workflows/rolling-release.yml`

Main entry points: [`bridge/bridge.go`](https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/bridge.go) (Native bridge), [`frontend/src/router/routes.ts`](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/router/routes.ts) (Feature routes), [`frontend/src/bridge/index.ts`](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/bridge/index.ts) (Typed bridge wrappers), [`frontend/src/views/HomeView/index.vue`](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/views/HomeView/index.vue) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native Host"]
  node_wails_host{{"Wails host<br/>Go entry point<br/>[main.go]"}}
  node_native_bridge["Native bridge<br/>Go bridge package<br/>[bridge.go]"]
  node_process_manager["Process manager<br/>native execution<br/>[exec.go]"]
  node_local_server["Local server support<br/>native server<br/>[server.go]"]
  node_system_integration["System proxy and tray<br/>OS integration<br/>[system_proxy.go]"]
end

subgraph group_frontend["Vue Frontend"]
  node_vue_bootstrap["Vue bootstrap<br/>frontend entry<br/>[main.ts]"]
  node_app_shell["Application shell<br/>Vue shell<br/>[App.vue]"]
  node_routes["Feature routes<br/>Vue router<br/>[routes.ts]"]
  node_profile_editor["Profile editor<br/>configuration UI<br/>[ProfileEditor.vue]"]
  node_domain_stores[("Domain stores<br/>Pinia stores<br/>[profiles.ts]")]
  node_frontend_bridge["Typed bridge wrappers<br/>TypeScript bridge<br/>[index.ts]"]
  node_kernel_client["Kernel API client<br/>HTTP and WebSocket API<br/>[kernel.ts]"]
  node_dashboard["Dashboard<br/>operational UI<br/>[index.vue]"]
end

subgraph group_runtime["Managed Runtime"]
  node_singbox_kernel{{"Sing-box kernel<br/>managed proxy core"}}
  node_kernel_api["Kernel HTTP/WebSocket<br/>live control surface"]
end

node_operating_system(("Operating system<br/>platform services"))
node_release_automation["Release automation<br/>GitHub Actions<br/>[release.yml]"]

node_wails_host -->|"binds"| node_native_bridge
node_wails_host -->|"hosts"| node_vue_bootstrap
node_native_bridge -->|"uses"| node_process_manager
node_native_bridge -->|"uses"| node_local_server
node_native_bridge -->|"uses"| node_system_integration
node_process_manager -->|"launches and stops"| node_singbox_kernel
node_system_integration -->|"integrates with"| node_operating_system
node_local_server -->|"uses"| node_operating_system
node_vue_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"renders route views"| node_routes
node_routes -->|"selects"| node_dashboard
node_routes -->|"selects"| node_profile_editor
node_profile_editor -->|"edits configuration"| node_domain_stores
node_dashboard -->|"reads control state"| node_domain_stores
node_domain_stores -->|"persists via"| node_frontend_bridge
node_frontend_bridge -->|"Wails calls"| node_native_bridge
node_frontend_bridge -->|"runtime commands"| node_process_manager
node_dashboard -->|"uses"| node_kernel_client
node_kernel_client -->|"HTTP/WebSocket"| node_kernel_api
node_kernel_api -->|"controls and streams"| node_singbox_kernel
node_release_automation -.->|"packages"| node_wails_host

click node_wails_host "https://github.com/gui-for-cores/gui.for.singbox/blob/main/main.go"
click node_native_bridge "https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/bridge.go"
click node_process_manager "https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/exec.go"
click node_local_server "https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/server.go"
click node_system_integration "https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/system_proxy.go"
click node_vue_bootstrap "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/main.ts"
click node_app_shell "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/App.vue"
click node_routes "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/router/routes.ts"
click node_profile_editor "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/views/ProfilesView/components/ProfileEditor.vue"
click node_domain_stores "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/stores/profiles.ts"
click node_frontend_bridge "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/bridge/index.ts"
click node_kernel_client "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/api/kernel.ts"
click node_dashboard "https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/views/HomeView/index.vue"
click node_release_automation "https://github.com/gui-for-cores/gui.for.singbox/blob/main/.github/workflows/release.yml"

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_wails_host,node_native_bridge,node_process_manager,node_local_server,node_system_integration toneBlue
class node_vue_bootstrap,node_app_shell,node_routes,node_profile_editor,node_domain_stores,node_frontend_bridge,node_kernel_client,node_dashboard toneAmber
class node_singbox_kernel,node_kernel_api toneMint
class node_operating_system,node_release_automation toneNeutral
```

## Components

### Native Host

Go/Wails host and OS integration.

- [Wails host](https://github.com/gui-for-cores/gui.for.singbox/blob/main/main.go): Go entry point · Embeds and launches the desktop application. · `main.go`
- [Native bridge](https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/bridge.go): Go bridge package · Exposes native capabilities through Wails bindings. · `bridge/bridge.go`
- [Process manager](https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/exec.go): native execution · Starts and manages the Sing-box process. · `bridge/exec.go`
- [Local server support](https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/server.go): native server · `bridge/server.go`
- [System proxy and tray](https://github.com/gui-for-cores/gui.for.singbox/blob/main/bridge/system_proxy.go): OS integration · `bridge/system_proxy.go`

### Vue Frontend

Desktop UI, state, and kernel control.

- [Vue bootstrap](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/main.ts): frontend entry · Initializes Vue and application lifecycle. · `frontend/src/main.ts`
- [Application shell](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/App.vue): Vue shell · Owns navigation, title bar, splash, and global overlays. · `frontend/src/App.vue`
- [Feature routes](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/router/routes.ts): Vue router · Routes operational feature domains. · `frontend/src/router/routes.ts`
- [Profile editor](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/views/ProfilesView/components/ProfileEditor.vue): configuration UI · Edits structured Sing-box configuration. · `frontend/src/views/ProfilesView/components/ProfileEditor.vue`
- [Domain stores](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/stores/profiles.ts): Pinia stores · Hold settings, profiles, subscriptions, rulesets, plugins, tasks, and logs. · `frontend/src/stores/profiles.ts`
- [Typed bridge wrappers](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/bridge/index.ts): TypeScript bridge · Frontend boundary for native filesystem and execution actions. · `frontend/src/bridge/index.ts`
- [Kernel API client](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/api/kernel.ts): HTTP and WebSocket API · Controls and observes the running core. · `frontend/src/api/kernel.ts`
- [Dashboard](https://github.com/gui-for-cores/gui.for.singbox/blob/main/frontend/src/views/HomeView/index.vue): operational UI · Shows live connections, traffic, logs, and quick actions. · `frontend/src/views/HomeView/index.vue`

### Managed Runtime

Sing-box execution and live API surface.

- **Sing-box kernel**: managed proxy core · Runs the selected generated proxy configuration.
- **Kernel HTTP/WebSocket**: live control surface · Exposes runtime control and telemetry.

### Other components

- **Operating system**: platform services · Provides system proxy, tray, filesystem, and process facilities.
- [Release automation](https://github.com/gui-for-cores/gui.for.singbox/blob/main/.github/workflows/release.yml): GitHub Actions · Builds release and rolling-release artifacts. · `.github/workflows/release.yml`

## Connections

- Wails host → Native bridge: binds
- Wails host → Vue bootstrap: hosts
- Native bridge → Process manager: uses
- Native bridge → Local server support: uses
- Native bridge → System proxy and tray: uses
- Process manager → Sing-box kernel: launches and stops
- System proxy and tray → Operating system: integrates with
- Local server support → Operating system: uses
- Vue bootstrap → Application shell: mounts
- Application shell → Feature routes: renders route views
- Feature routes → Dashboard: selects
- Feature routes → Profile editor: selects
- Profile editor → Domain stores: edits configuration
- Dashboard → Domain stores: reads control state
- Domain stores → Typed bridge wrappers: persists via
- Typed bridge wrappers → Native bridge: Wails calls
- Typed bridge wrappers → Process manager: runtime commands
- Dashboard → Kernel API client: uses
- Kernel API client → Kernel HTTP/WebSocket: HTTP/WebSocket
- Kernel HTTP/WebSocket → Sing-box kernel: controls and streams
- Release automation → Wails host: packages
