Reference Projects & Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Reference projects and integrations allow HX-ProxyGroup to study external proxy management designs while maintaining a strict architectural boundary. The project organizes external research materials in the ref/ directory, which is excluded from the core source code via .gitignore. These projects provide insights into subscription parsing conventions and node lifecycle management without direct code duplication.
HX-ProxyGroup integrates with external tools through formal contracts, specifically for AI agents and consumer-facing APIs. These integrations are enforced through validation scripts that ensure the server implementation, documentation, and agent skills remain synchronized.
Reference Projects Management
Reference projects are stored in the ref/ directory for research purposes. The project uses a synchronization script to manage these repositories.
Synchronization Logic
The scripts/sync-reference.sh script performs the following actions:
- Executes a shallow clone if the directory does not exist.
- Performs a fast-forward update if the Git repository already exists.
- Aborts the operation if the local workspace contains uncommitted changes.
- Avoids using
reset --hardto prevent accidental loss of local research notes.
Sources: ref/README.md:55-67, scripts/sync-reference.sh
Studied Projects
| Project | Purpose | Key Capabilities Researched |
|---|---|---|
| BPB-Worker-Panel | VLESS/Trojan study | sub/raw subscription conventions, DoH address rotation, and WebSocket routing logic. |
| easy-proxies | Node management | Node lifecycle (candidate, pooled, failed), concurrent testing, and multi-port gateway modes. |
Sources: ref/README.md:5-53
Integration Boundaries
HX-ProxyGroup maintains a clear distinction between researched designs and its own implementation:
- Protocol Implementation: v1 uses a managed Mihomo process as the data plane. It does not implement protocol kernels (like VMess or Trojan) directly within the control plane.
- Licensing: The project strictly avoids copying code from GPL-3.0 projects like BPB-Worker-Panel to maintain license compatibility.
- Architecture: HX-ProxyGroup prioritizes a "Multiple Subscriptions + Rule Pipeline + Proxy Group" model rather than the one-node-per-port model seen in some reference projects.
Sources: AGENTS.md:12-19, ref/README.md:19-27, ref/README.md:46-53
Integration Contracts & Validation
Integrations are governed by strict contracts to prevent "documentation drift" between the server, external agents, and consumer clients.
Consumer Integration Contract
The consumer contract ensures that the nodes rendered for public consumption match the documentation and agent skills.
The diagram shows the three-way synchronization enforced by the consumer contract gate.
The validation script scripts/verify-consumer-contract.ts enforces that:
- The public listing endpoint does not live under
/api/to avoid collision with session-authenticated administrator space. - Vocabularies for fields, protocols, transports, and formats are identical across all three source files.
Sources: scripts/verify-consumer-contract.ts:1-73
Admin Capability Catalog
AI agents driving the management API rely on the Capability Catalog. This is a contract that allows agents to interact with the system without reading Go source code.
The sequence diagram illustrates how agents must learn paths dynamically from the catalog rather than using hard-coded values.
The scripts/verify-admin-catalog.ts gate ensures:
- The skill documents only endpoints that the server actually publishes.
- Automation scripts do not hard-code paths (except for the catalog path itself), forcing them to learn paths at runtime from the catalog response.
- Enums referenced in the catalog exist in the internal types.
Sources: scripts/verify-admin-catalog.ts:1-125
Development Constraints for Agents
HX-ProxyGroup includes an AGENTS.md file that constrains how AI agents modify the codebase.
Core Rules for AI/Agent Development
- Memory Management: Agents must never write process memory or decision logs back into
AGENTS.md. All status and lessons must be stored in thedocs/directory. - Technical Stack: Agents must adhere to the fixed stack: Go (standard library priority), SQLite + WAL, and React + Tailwind CSS.
- Layering Enforcement: Agents are forbidden from creating shortcuts between layers (e.g., Handlers writing SQL directly or Frontend accessing Mihomo Controller directly).
Sources: AGENTS.md:5-45
Implementation Standards
| Category | Requirement |
|---|---|
| Concurrency | All goroutines must have explicit owners and exit paths. No unindexed tickers. |
| Security | Secrets (Tokens, Passwords) must never be logged. API Listeners default to loopback. |
| Testing | New features must include unit tests for logic and integration tests for SQLite/Mihomo boundaries. |
| Configuration | Changes must be atomic; failed applications must rollback to the previous version. |
Sources: AGENTS.md:56-94
System Integrations & Diagnostics
The project integrates with the host system for lifecycle and performance monitoring.
System Information Integration
The control plane exposes system info and data plane versions through the /api/v1/system/info endpoint.
- Data Plane: Integrates with Mihomo to report versioning (e.g., "Mihomo Meta 1.20.0").
- Supported Protocols: Reports the protocol set supported by the current data plane build.
Sources: web/src/pages/about-page.tsx:88-92, internal/api/system_static_test.go:88-112
Update Integration
HX-ProxyGroup integrates with a systemd-based installer for updates.
- The web UI triggers a POST to
/api/v1/system/update. - This requires a 2FA step-up verification for security.
- The server executes a fixed command:
sudo hx-proxygroup-install upgrade. - The systemd readiness check ensures the service recovers or rolls back automatically.
Sources: web/src/pages/about-page.tsx:37-58, internal/api/system_static_test.go:128-150, install.sh:267-285
HX-ProxyGroup maintains architectural integrity by treating reference projects as external research, while enforcing strict, machine-validated contracts for AI agents and consumer integrations.