# hiddify/hiddify-core architecture

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

- Interactive diagram: https://gitdiagram.com/hiddify/hiddify-core
- Repository: https://github.com/hiddify/hiddify-core

## Overview

Hiddify Core is a cross-platform proxy engine and service layer built on sing-box. A typical user workflow is to supply a proxy configuration or profile, start the core, and route traffic through its supported protocols; platform apps can also use privileged VPN service support. The repository additionally documents router mode and third-party extensions with custom UI and config hooks. The graph retains these documented capabilities, but several links are dashed because their implementation was not sampled; solid links are limited to relationships visible in excerpts.

Main entry points: [`v2/hcore/service.go`](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/service.go) (Core service), [`v2/profile/profile_repository.go`](https://github.com/hiddify/hiddify-core/blob/main/v2/profile/profile_repository.go) (Profile repository), [`extension/extension.go`](https://github.com/hiddify/hiddify-core/blob/main/extension/extension.go) (Extension API), [`cmd/grpcweb/server.go`](https://github.com/hiddify/hiddify-core/blob/main/cmd/grpcweb/server.go) (gRPC web harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and API"]
  node_cli["CLI commands"]
  node_grpcweb["gRPC web harness<br/>[server.go]"]
  node_grpc["Core gRPC API<br/>[grpc_server.go]"]
end

subgraph group_profiles["Profiles and config"]
  node_profilesvc["Profile repository"]
  node_profileparse["Profile parser<br/>[profile_parser.go]"]
  node_config["Config builder<br/>[builder.go]"]
  node_db[("Local database<br/>[hiddify_db.go]")]
end

subgraph group_runtime["Proxy runtime"]
  node_core["Core service<br/>[service.go]"]
  node_lifecycle["Core lifecycle<br/>[start.go]"]
  node_singbox["sing-box engine"]
  node_router["Router mode<br/>[router_mode.go]"]
end

subgraph group_service["Platform services"]
  node_admincmd["Foreground service command"]
  node_adminapi["Privileged VPN service"]
  node_admincore["Admin core service<br/>[admin_bgservice.go]"]
  node_desktop["Desktop integration<br/>[custom.go]"]
  node_mobile["Mobile integration<br/>[mobile.go]"]
end

subgraph group_extensions["Extensions"]
  node_extapi["Extension API<br/>[extension.go]"]
  node_exthost["Extension host<br/>[extension_host.go]"]
  node_extui["Extension UI<br/>[form.go]"]
  node_extsdk["Extension SDK<br/>[interface.go]"]
  node_extweb["Extension browser UI<br/>[client.js]"]
end

node_user(("App user"))

node_user -.->|"runs"| node_cli
node_cli -.->|"launches"| node_grpcweb
node_grpcweb -->|"registers"| node_grpc
node_user -.->|"manages profiles"| node_profilesvc
node_profilesvc -->|"reads and writes"| node_db
node_profilesvc -.->|"parses profiles"| node_profileparse
node_profilesvc -.->|"uses config"| node_config
node_user -.->|"controls core"| node_grpc
node_grpcweb -->|"starts core"| node_core
node_core -.->|"manages lifecycle"| node_lifecycle
node_lifecycle -.->|"runs engine"| node_singbox
node_config -.->|"configures protocols"| node_singbox
node_router -.->|"enables routing"| node_singbox
node_admincmd -->|"starts service"| node_adminapi
node_adminapi -->|"starts full core"| node_admincore
node_adminapi -->|"creates service"| node_core
node_desktop -.->|"integrates core"| node_core
node_mobile -.->|"integrates core"| node_core
node_user -.->|"uses extensions"| node_extweb
node_extweb -.->|"calls extension API"| node_exthost
node_exthost -.->|"hosts extensions"| node_extapi
node_extapi -.->|"renders custom UI"| node_extui
node_extapi -.->|"exposes SDK"| node_extsdk
node_extapi -.->|"modifies configs"| node_config

click node_cli "https://github.com/hiddify/hiddify-core/tree/main/cmd"
click node_grpcweb "https://github.com/hiddify/hiddify-core/blob/main/cmd/grpcweb/server.go"
click node_grpc "https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/grpc_server.go"
click node_profilesvc "https://github.com/hiddify/hiddify-core/blob/main/v2/profile/profile_repository.go"
click node_profileparse "https://github.com/hiddify/hiddify-core/blob/main/v2/profile/profile_parser.go"
click node_config "https://github.com/hiddify/hiddify-core/blob/main/v2/config/builder.go"
click node_db "https://github.com/hiddify/hiddify-core/blob/main/v2/db/hiddify_db.go"
click node_core "https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/service.go"
click node_lifecycle "https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/start.go"
click node_router "https://github.com/hiddify/hiddify-core/blob/main/v2/config/router_mode.go"
click node_admincmd "https://github.com/hiddify/hiddify-core/blob/main/cmd/cmd_core_service.go"
click node_adminapi "https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/adminbgservice/admin_bg_service.go"
click node_admincore "https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/admin_bgservice.go"
click node_desktop "https://github.com/hiddify/hiddify-core/blob/main/platform/desktop/custom.go"
click node_mobile "https://github.com/hiddify/hiddify-core/blob/main/platform/mobile/mobile.go"
click node_extapi "https://github.com/hiddify/hiddify-core/blob/main/extension/extension.go"
click node_exthost "https://github.com/hiddify/hiddify-core/blob/main/extension/extension_host.go"
click node_extui "https://github.com/hiddify/hiddify-core/blob/main/extension/ui/form.go"
click node_extsdk "https://github.com/hiddify/hiddify-core/blob/main/extension/sdk/interface.go"
click node_extweb "https://github.com/hiddify/hiddify-core/blob/main/extension/html/rpc/client.js"

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_cli,node_grpcweb,node_grpc,node_user toneBlue
class node_profilesvc,node_profileparse,node_config,node_db toneAmber
class node_core,node_lifecycle,node_singbox,node_router toneMint
class node_admincmd,node_adminapi,node_admincore,node_desktop,node_mobile toneRose
class node_extapi,node_exthost,node_extui,node_extsdk,node_extweb toneIndigo
```

## Components

### Entry and API

- [CLI commands](https://github.com/hiddify/hiddify-core/tree/main/cmd): `cmd`
- [gRPC web harness](https://github.com/hiddify/hiddify-core/blob/main/cmd/grpcweb/server.go): `cmd/grpcweb/server.go`
- [Core gRPC API](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/grpc_server.go): `v2/hcore/grpc_server.go`

### Profiles and config

- [Profile repository](https://github.com/hiddify/hiddify-core/blob/main/v2/profile/profile_repository.go): `v2/profile/profile_repository.go`
- [Profile parser](https://github.com/hiddify/hiddify-core/blob/main/v2/profile/profile_parser.go): `v2/profile/profile_parser.go`
- [Config builder](https://github.com/hiddify/hiddify-core/blob/main/v2/config/builder.go): `v2/config/builder.go`
- [Local database](https://github.com/hiddify/hiddify-core/blob/main/v2/db/hiddify_db.go): `v2/db/hiddify_db.go`

### Proxy runtime

- [Core service](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/service.go): `v2/hcore/service.go`
- [Core lifecycle](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/start.go): `v2/hcore/start.go`
- **sing-box engine**
- [Router mode](https://github.com/hiddify/hiddify-core/blob/main/v2/config/router_mode.go): `v2/config/router_mode.go`

### Platform services

- [Foreground service command](https://github.com/hiddify/hiddify-core/blob/main/cmd/cmd_core_service.go): `cmd/cmd_core_service.go`
- [Privileged VPN service](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/adminbgservice/admin_bg_service.go): `v2/hcore/adminbgservice/admin_bg_service.go`
- [Admin core service](https://github.com/hiddify/hiddify-core/blob/main/v2/hcore/admin_bgservice.go): `v2/hcore/admin_bgservice.go`
- [Desktop integration](https://github.com/hiddify/hiddify-core/blob/main/platform/desktop/custom.go): `platform/desktop/custom.go`
- [Mobile integration](https://github.com/hiddify/hiddify-core/blob/main/platform/mobile/mobile.go): `platform/mobile/mobile.go`

### Extensions

- [Extension API](https://github.com/hiddify/hiddify-core/blob/main/extension/extension.go): `extension/extension.go`
- [Extension host](https://github.com/hiddify/hiddify-core/blob/main/extension/extension_host.go): `extension/extension_host.go`
- [Extension UI](https://github.com/hiddify/hiddify-core/blob/main/extension/ui/form.go): `extension/ui/form.go`
- [Extension SDK](https://github.com/hiddify/hiddify-core/blob/main/extension/sdk/interface.go): `extension/sdk/interface.go`
- [Extension browser UI](https://github.com/hiddify/hiddify-core/blob/main/extension/html/rpc/client.js): `extension/html/rpc/client.js`

### Other components

- **App user**

## Connections

- App user → CLI commands: runs
- CLI commands → gRPC web harness: launches
- gRPC web harness → Core gRPC API: registers (evidence: `cmd/grpcweb/server.go`)
- App user → Profile repository: manages profiles (evidence: `README.md`)
- Profile repository → Local database: reads and writes (evidence: `v2/profile/profile_repository.go`)
- Profile repository → Profile parser: parses profiles
- Profile repository → Config builder: uses config
- App user → Core gRPC API: controls core
- gRPC web harness → Core service: starts core (evidence: `cmd/grpcweb/server.go`)
- Core service → Core lifecycle: manages lifecycle
- Core lifecycle → sing-box engine: runs engine
- Config builder → sing-box engine: configures protocols (evidence: `README.md`)
- Router mode → sing-box engine: enables routing (evidence: `README.md`)
- Foreground service command → Privileged VPN service: starts service (evidence: `cmd/cmd_core_service.go`)
- Privileged VPN service → Admin core service: starts full core (evidence: `v2/hcore/adminbgservice/admin_bg_service.go`)
- Privileged VPN service → Core service: creates service (evidence: `v2/hcore/adminbgservice/admin_bg_service.go`)
- Desktop integration → Core service: integrates core (evidence: `README.md`)
- Mobile integration → Core service: integrates core (evidence: `README.md`)
- App user → Extension browser UI: uses extensions (evidence: `README.md`)
- Extension browser UI → Extension host: calls extension API
- Extension host → Extension API: hosts extensions (evidence: `README.md`)
- Extension API → Extension UI: renders custom UI (evidence: `README.md`)
- Extension API → Extension SDK: exposes SDK (evidence: `README.md`)
- Extension API → Config builder: modifies configs (evidence: `README.md`)