React Web Dashboard UI
Relevant source files
The following files were used as context for generating this wiki page:
The React Web Dashboard UI provides a graphical management interface for the HX-ProxyGroup control plane. It enables administrators to monitor real-time traffic, manage proxy subscriptions and nodes, configure routing rules, and perform system maintenance through a browser-based shell and various specialized pages. The UI is built using React, TypeScript, and Tailwind CSS, following a single-page application (SPA) architecture that communicates with a Go-based backend via REST and Server-Sent Events (SSE).
Sources: web/src/App.tsx:23-53, AGENTS.md:39-44
Application Architecture
The UI utilizes a lazy-loading strategy where each major module is split into separate chunks to optimize the initial paint. The App.tsx component serves as the layout root, managing the sidebar navigation, authentication state, and global notifications.
Navigation and Routing
The dashboard uses a hash-based routing system. A sidebar provides access to primary modules, including Overview, Subscriptions, Routing, Rules, and Settings.
The application maintains a connection health status by polling the /health endpoint every 15 seconds.
Sources: web/src/App.tsx:75-87, web/src/App.tsx:149-161
Authentication and Security
The UI implements an AuthGate to control access. If the system is unconfigured, the AuthPage presents an initialization form requiring a setup-token from the server's data directory. For configured systems, it requires standard username and password credentials.
Authentication Flow
Security features managed in the UI include:
- CSRF Protection: Tokens are managed via
setCsrfTokenin the API library. - Two-Factor Authentication (2FA): The
SettingsPageallows enabling TOTP-based 2FA, which is required for sensitive operations like system updates. - API Key Management: Administrators can create and revoke API keys for external script integration.
Sources: web/src/pages/auth-page.tsx:18-40, web/src/pages/settings-page.tsx:128-175
Core Functional Modules
Overview Dashboard
The Overview page provides a real-time summary of the system status. It features a traffic chart that visualizes upload and download rates using data streamed via EventSource (SSE).
| Component | Description |
|---|---|
| Status Band | Shows Mihomo runtime status and SSE stream connectivity. |
| Metrics Grid | Displays current upload/download rates, active connections, and valid listeners. |
| Traffic Chart | An SVG-based visualization of second-level sampling data for the last 30-120 seconds. |
| Route Topology | Lists all entry listeners and their associated proxy groups and rule sets. |
Sources: web/src/pages/overview-page.tsx:82-114
Routing and Proxy Services
The Routing page is the primary interface for managing ListenerRecord and ProxyGroup entities. It supports two modes: per-service ports or a "Shared Inbound" mode where multiple services share a single port via username-based multiplexing.
Sources: web/src/pages/routing-page.tsx:57-96
System Resource Monitoring
The UI tracks host performance through two distinct components:
- HostResources: Displayed on the Overview page, polling at a 10s cadence to show CPU and Memory for the
hx-proxygroupdandmihomoprocesses. - OpsPage: A sub-tab in the Terminal module providing 3s high-frequency polling for CPU, RAM, Load, Network I/O, and Disk usage.
Sources: web/src/components/host-resources.tsx:21-46, web/src/components/terminal/ops-page.tsx:23-44
Artifacts and Backup
The Artifacts page manages system snapshots. Users can create two types of archives:
- Backup: An online SQLite backup containing the full database state.
- Portable Export: A non-sensitive state export excluding secrets and credentials.
Sources: web/src/pages/artifacts-page.tsx:39-77
Technical Implementation Details
State Management
The project strictly separates server state (fetched from API) and local UI state (e.g., sidebar collapse, active tabs).
- API Interaction: The
apiobject inweb/src/lib/api.tscentralizes all backend communication. - Real-time Updates:
EventSourceis used for traffic samples and terminal metrics to minimize overhead compared to WebSocket.
UI Components
The interface uses a set of standardized UI components:
- Tabs: Managed via
@radix-ui/react-tabsfor navigation within pages like Settings and Inventory. - Mermaid Diagrams: While not present in the source code themselves, the UI uses SVG and SVG path generators (e.g.,
chartPath,resourcePath) to render custom traffic visualizations.
Sources: web/src/pages/overview-page.tsx:206-220, web/src/components/ui/tabs.tsx:5-12
The React Web Dashboard UI serves as the central orchestration point for the HX-ProxyGroup ecosystem, providing the necessary tools for monitoring, configuration, and maintenance while maintaining a strict boundary between the control plane UI and the data plane traffic forwarding.
Sources: AGENTS.md:14-16