# greepar/hypanel architecture

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

- Interactive diagram: https://gitdiagram.com/greepar/hypanel
- Repository: https://github.com/greepar/hypanel

## Overview

HyPanel is a web control panel for centrally managing proxy services across enrolled nodes. Administrators configure nodes, services, users, groups, certificates, and updates in the browser; the Server persists panel state and coordinates with Agents, which enroll and actively poll for desired state and commands, then reconcile services and report status. Users receive Clash/Mihomo subscriptions. The README documents backup/restore and online updates as additional capabilities. Some subsystem links are based on documented responsibilities and paths; unsampled implementation details are not inferred.

Main entry points: [`src/HyPanel.Agent/Sync/SyncWorker.cs`](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Sync/SyncWorker.cs) (Sync worker), [`src/HyPanel.Server/Endpoints`](https://github.com/greepar/hypanel/tree/main/src/HyPanel.Server/Endpoints) (Admin endpoints), [`src/HyPanel.Agent/Reconciliation/ServiceReconciler.cs`](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Reconciliation/ServiceReconciler.cs) (Service reconciler), [`src/HyPanel.Server/Endpoints/SubscriptionEndpoints.cs`](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/SubscriptionEndpoints.cs) (Subscriptions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web panel"]
  node_webapp["Panel UI<br/>[app.tsx]"]
  node_webapi["API client<br/>[api.ts]"]
end

subgraph group_server["Control plane"]
  node_subscription["Subscriptions"]
  node_adminapi["Admin endpoints<br/>[Endpoints]"]
  node_enrollment["Enrollment"]
  node_syncapi["Agent sync API"]
  node_repository[("Panel repository")]
  node_certs["Certificate management"]
end

subgraph group_agent["Node agent"]
  node_identity["Agent identity"]
  node_syncworker["Sync worker<br/>[SyncWorker.cs]"]
  node_reconciler["Service reconciler"]
  node_providers["Backend providers<br/>[Backends]"]
  node_runtime["Process supervision"]
  node_artifacts["Backend artifacts"]
  node_porthopping["Port hopping"]
end

subgraph group_operations["Operations"]
  node_releases["Release catalog<br/>[ReleaseCatalog.cs]"]
  node_agentupdates["Agent updates<br/>[AgentUpdater.cs]"]
  node_serverupdates["Server updates"]
  node_backup["Backup and restore"]
end

node_admin(("Administrator"))
node_user(("Subscription user"))
node_agent(("Node Agent<br/>[Program.cs]"))
node_proxyclients(("Proxy clients"))

node_admin -->|"uses"| node_webapp
node_webapp -->|"requests"| node_webapi
node_webapi -->|"calls"| node_adminapi
node_webapi -->|"fetches"| node_subscription
node_user -->|"requests"| node_subscription
node_subscription -->|"reads"| node_repository
node_adminapi -->|"reads and writes"| node_repository
node_adminapi -->|"issues tokens"| node_enrollment
node_agent -->|"ensures identity"| node_identity
node_identity -->|"enrolls over HTTPS"| node_enrollment
node_agent -->|"runs"| node_syncworker
node_syncworker -->|"polls and reports"| node_syncapi
node_syncapi -->|"exchanges state"| node_repository
node_syncworker -->|"applies desired state"| node_reconciler
node_reconciler -->|"validates and configures"| node_providers
node_reconciler -->|"ensures binaries"| node_artifacts
node_reconciler -->|"starts and monitors"| node_runtime
node_syncworker -->|"applies rules"| node_porthopping
node_adminapi -->|"manages"| node_certs
node_agentupdates -->|"receives offers"| node_syncworker
node_syncworker -->|"applies offers"| node_agentupdates
node_releases -->|"provides artifacts"| node_syncapi
node_adminapi -->|"manages backups"| node_backup
node_serverupdates -.->|"checks releases"| node_releases
node_proxyclients -->|"consumes"| node_subscription

click node_webapp "https://github.com/greepar/hypanel/blob/main/web/HyPanel.Web/src/app.tsx"
click node_webapi "https://github.com/greepar/hypanel/blob/main/web/HyPanel.Web/src/api.ts"
click node_subscription "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/SubscriptionEndpoints.cs"
click node_adminapi "https://github.com/greepar/hypanel/tree/main/src/HyPanel.Server/Endpoints"
click node_enrollment "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Persistence/EnrollmentService.cs"
click node_syncapi "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/AgentSyncEndpoints.cs"
click node_repository "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Persistence/SqliteServerRepository.cs"
click node_agent "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Program.cs"
click node_identity "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Enrollment/AgentIdentityManager.cs"
click node_syncworker "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Sync/SyncWorker.cs"
click node_reconciler "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Reconciliation/ServiceReconciler.cs"
click node_providers "https://github.com/greepar/hypanel/tree/main/src/HyPanel.Agent/Backends"
click node_runtime "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/BackendProcessSupervisor.cs"
click node_artifacts "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/BackendBinaryManager.cs"
click node_porthopping "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/PortHoppingManager.cs"
click node_certs "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/AdminCertificatesEndpoints.cs"
click node_releases "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Releases/ReleaseCatalog.cs"
click node_agentupdates "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Updates/AgentUpdater.cs"
click node_serverupdates "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Updates/ServerUpdateService.cs"
click node_backup "https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Backup/BackupRestoreService.cs"

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_webapp,node_webapi,node_user,node_proxyclients toneBlue
class node_subscription,node_adminapi,node_enrollment,node_syncapi,node_repository,node_certs toneAmber
class node_identity,node_syncworker,node_reconciler,node_providers,node_runtime,node_artifacts,node_porthopping toneMint
class node_releases,node_agentupdates,node_serverupdates,node_backup toneRose
class node_admin toneIndigo
class node_agent toneTeal
```

## Components

### Web panel

- [Panel UI](https://github.com/greepar/hypanel/blob/main/web/HyPanel.Web/src/app.tsx): `web/HyPanel.Web/src/app.tsx`
- [API client](https://github.com/greepar/hypanel/blob/main/web/HyPanel.Web/src/api.ts): `web/HyPanel.Web/src/api.ts`

### Control plane

- [Subscriptions](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/SubscriptionEndpoints.cs): `src/HyPanel.Server/Endpoints/SubscriptionEndpoints.cs`
- [Admin endpoints](https://github.com/greepar/hypanel/tree/main/src/HyPanel.Server/Endpoints): `src/HyPanel.Server/Endpoints`
- [Enrollment](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Persistence/EnrollmentService.cs): `src/HyPanel.Server/Persistence/EnrollmentService.cs`
- [Agent sync API](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/AgentSyncEndpoints.cs): `src/HyPanel.Server/Endpoints/AgentSyncEndpoints.cs`
- [Panel repository](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Persistence/SqliteServerRepository.cs): `src/HyPanel.Server/Persistence/SqliteServerRepository.cs`
- [Certificate management](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Endpoints/AdminCertificatesEndpoints.cs): `src/HyPanel.Server/Endpoints/AdminCertificatesEndpoints.cs`

### Node agent

- [Agent identity](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Enrollment/AgentIdentityManager.cs): `src/HyPanel.Agent/Enrollment/AgentIdentityManager.cs`
- [Sync worker](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Sync/SyncWorker.cs): `src/HyPanel.Agent/Sync/SyncWorker.cs`
- [Service reconciler](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Reconciliation/ServiceReconciler.cs): `src/HyPanel.Agent/Reconciliation/ServiceReconciler.cs`
- [Backend providers](https://github.com/greepar/hypanel/tree/main/src/HyPanel.Agent/Backends): `src/HyPanel.Agent/Backends`
- [Process supervision](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/BackendProcessSupervisor.cs): `src/HyPanel.Agent/Backends/Infrastructure/BackendProcessSupervisor.cs`
- [Backend artifacts](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/BackendBinaryManager.cs): `src/HyPanel.Agent/Backends/Infrastructure/BackendBinaryManager.cs`
- [Port hopping](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Backends/Infrastructure/PortHoppingManager.cs): `src/HyPanel.Agent/Backends/Infrastructure/PortHoppingManager.cs`

### Operations

- [Release catalog](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Releases/ReleaseCatalog.cs): `src/HyPanel.Server/Releases/ReleaseCatalog.cs`
- [Agent updates](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Updates/AgentUpdater.cs): `src/HyPanel.Agent/Updates/AgentUpdater.cs`
- [Server updates](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Updates/ServerUpdateService.cs): `src/HyPanel.Server/Updates/ServerUpdateService.cs`
- [Backup and restore](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Server/Backup/BackupRestoreService.cs): `src/HyPanel.Server/Backup/BackupRestoreService.cs`

### Other components

- **Administrator**
- **Subscription user**
- [Node Agent](https://github.com/greepar/hypanel/blob/main/src/HyPanel.Agent/Program.cs): `src/HyPanel.Agent/Program.cs`
- **Proxy clients**

## Connections

- Administrator → Panel UI: uses
- Panel UI → API client: requests
- API client → Admin endpoints: calls
- API client → Subscriptions: fetches
- Subscription user → Subscriptions: requests
- Subscriptions → Panel repository: reads
- Admin endpoints → Panel repository: reads and writes
- Admin endpoints → Enrollment: issues tokens
- Node Agent → Agent identity: ensures identity
- Agent identity → Enrollment: enrolls over HTTPS
- Node Agent → Sync worker: runs
- Sync worker → Agent sync API: polls and reports
- Agent sync API → Panel repository: exchanges state
- Sync worker → Service reconciler: applies desired state
- Service reconciler → Backend providers: validates and configures
- Service reconciler → Backend artifacts: ensures binaries
- Service reconciler → Process supervision: starts and monitors
- Sync worker → Port hopping: applies rules
- Admin endpoints → Certificate management: manages
- Agent updates → Sync worker: receives offers
- Sync worker → Agent updates: applies offers
- Release catalog → Agent sync API: provides artifacts
- Admin endpoints → Backup and restore: manages backups
- Server updates → Release catalog: checks releases
- Proxy clients → Subscriptions: consumes