Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
HX-ProxyGroup consists of a Go-based control plane and a Mihomo-based data plane. The control plane manages proxy configurations, subscriptions, and routing rules, while the data plane handles actual traffic forwarding. The system maintains a strict separation between management logic and the packet forwarding path.
Sources: AGENTS.md:15-18, SECURITY.md:13-16
Component Hierarchy
The system follows a strict layered architecture for both backend and frontend components.
Backend Layering
The backend enforces a unidirectional dependency flow:
API -> Application Service -> Domain/Interface -> Repository/DataPlane
Direct cross-layer shortcuts, such as handlers writing SQL or repositories calling HTTP APIs, are prohibited to maintain modularity.
Sources: AGENTS.md:38-46
Frontend Structure
The frontend is a React-based Single Page Application (SPA) built with TypeScript and Tailwind CSS. It communicates with the control plane via REST APIs and Server-Sent Events (SSE) for real-time monitoring data.
Sources: AGENTS.md:27-31, web/src/App.tsx:28-40
Process Model and Lifecycle
The production environment operates as a set of managed systemd services.
The diagram shows the relationship between the three main system processes and the persistent storage.
| Component | Service Name | Responsibility |
|---|---|---|
| Control Plane | hx-proxygroup.service | Management API, state persistence, configuration compilation. |
| Data Plane | hx-proxygroup-dataplane.service | Protocol handling and traffic forwarding via Mihomo. |
| Terminal Helper | hx-proxygroup-terminal.service | Root PTY management for the browser-based shell. |
Sources: install.sh:4-10, AGENTS.md:19-20, SECURITY.md:37-40
Data Flow and Persistence
Configuration Management
The SQLite database serves as the single source of truth for the desired state. Configuration changes follow an atomic update cycle:
- Generate a complete candidate configuration based on database state.
- Validate the candidate configuration against the Mihomo binary.
- Atomically publish the configuration to the data plane.
- Roll back to the previous version if the application fails.
Sources: AGENTS.md:73-77, install.sh:220-230
Observability Stream
Real-time metrics flow from the data plane to the frontend through an SSE (Server-Sent Events) stream.
The sequence diagram illustrates how the frontend initiates a persistent connection to receive live traffic updates.
Sources: internal/api/overview.go:17-45, web/src/pages/overview-page.tsx:61-88
Security Boundaries
The system enforces several security constraints:
- Loopback Bindings: The management API and Mihomo External Controller bind to loopback addresses by default.
- Authentication: Public proxy listeners and management endpoints are separate. Listeners must use explicit authentication when exposed.
- Sensitive Data: Logs exclude Authorization headers, cookies, and full subscription tokens.
- Terminal Access: Browser terminal access requires a configured administrator session and TOTP 2FA verification.
Sources: SECURITY.md:13-20, AGENTS.md:81-85, SECURITY.md:43-47
Installation and Deployment
The install.sh script manages the deployment lifecycle, including user creation, directory permission setting, and service orchestration. It supports both online release downloads and offline bundle installations.
| Path | Purpose | Permissions |
|---|---|---|
/usr/local/lib/hx-proxygroup | Binary and static asset versions | root:root |
/etc/hx-proxygroup | Configuration files (e.g., config.yaml) | root:hx-proxygroup (0750) |
/var/lib/hx-proxygroup | SQLite DB, snapshots, and artifacts | hx-proxygroup:hx-proxygroup (0700) |
Sources: install.sh:13-20, install.sh:110-125
Conclusion
HX-ProxyGroup provides a robust management layer for Mihomo by separating the control plane from the data plane. It uses a structured API-driven architecture, persistent storage in SQLite, and secure systemd-managed processes to ensure reliability and observability in proxy management.
Sources: AGENTS.md:15-18, AGENTS.md:73-77