4.7 KiB
4.7 KiB
Web User Interface (SPA) Architecture & Route Reference
nx9-wg embeds a complete, zero-dependency HTML5/CSS/JavaScript Single Page Application (SPA) directly inside the Rust binary.
1. Frontend Architecture & Design System
- Zero External Toolchains: Built entirely in standard HTML5, CSS3, and modern Vanilla ES6+ JavaScript. No Node.js, npm, Webpack, Vite, React, or external CDN dependencies.
- Embedded Static Assets: HTML, CSS, and JavaScript are bundled into the binary at compile time via
include_str!()and served from memory. - Unified Design Tokens: Custom CSS variable design system (
nx9-wg-ui/src/css.rs) providing Dark and Light themes with persistentlocalStoragepreference. - Responsive Layout: Mobile-first responsive layout with side-drawer navigation and
@media (max-width: 768px)breakpoints. - Live WebSocket Event Stream: Connects to
ws://<host>/api/v1/wsfor reactive dashboard, peer handshake, and reconciliation updates without polling. - Presentation-Only Separation: The UI contains presentation and client routing logic only; all business validation, allocation, and state authority reside in the backend REST API and SQLite.
2. Complete Route Inventory
| Hash Route | Navigation Label | Purpose & Operational Features |
|---|---|---|
#dashboard |
Dashboard | System status, uptime, interface/peer counts, diagnostics health, and reconciliation status cards. |
#interfaces |
Interfaces | List WireGuard interfaces, "+ Create Interface" modal, enable/disable toggle, and delete interface. |
#peers |
Peers | Enrolled peer table with real-time handshakes, status filter, "+ Add Peer" modal with MTU profile resolution, client configuration export, and live SVG QR rendering. |
#networks |
Networks | Subnet network ranges, CIDR masks, "+ Create Network" modal, and deletion. |
#routes |
Routes | Routing table entries, gateway assignments, "+ Create Route" modal, and deletion. |
#firewall |
Firewall | nftables packet filtering rules in table inet nx9_wg, "+ Create Rule" modal, priority ordering, and enable/disable toggle. |
#nat |
NAT & Masquerade | Outbound NAT masquerade status card, active masqueraded subnet list, and instant toggle. |
#forwarding |
IP Forwarding | Kernel sysctl /proc/sys/net/ipv4/ip_forward packet forwarding status and toggle. |
#reconciliation |
Reconciliation | Real-time kernel drift overview, planned execution actions table, and interactive "Run Reconcile (Apply)" button. |
#diagnostics |
Diagnostics | Automated health inspection across all 9 subsystems (system, network, wireguard, peer, routing, forwarding, firewall, nat, reconciliation) with remediation hints. |
#live-state |
Live State | Live Linux Netlink kernel telemetry, active WireGuard interfaces, and live routing table entries. |
#settings |
Settings | Appliance key-value parameters table and danger zone reset controls. |
#backups |
Backups | Atomic SQLite database backup snapshots list, "+ Create Backup Snapshot" button, and direct .db download. |
#audit |
Audit Log | Append-only security and administrative audit trail with actor, IP, timestamp, and metadata. |
#administrator |
Administrator | Admin account verification, "Change Password" modal, and "+ Generate API Token" modal with one-time raw secret copy. |
3. Interactive Modals & Client Transport Profiles
A. Client Profile & MTU Resolution Modal
When enrolling a new peer (#peers), the modal automatically queries /api/v1/client-profiles/resolve based on selected Device (Android, iOS, Linux, Windows, macOS) and Connection (Mobile Cellular 4G/5G, Wi-Fi, Wired Ethernet) to determine optimal MTU (1280 vs 1360 vs 1420) and persistent keepalive (25s).
B. Client Export & QR Code Modal
Displays both:
- Interactive Vector QR Code: Inline SVG rendering for scanning directly with the official WireGuard mobile app.
- Downloadable
.confFile: Standard WireGuard client configuration file formatted for instant download or clipboard copy.
C. One-Time API Token Delivery Modal
Generates a new API token, calculates its SHA-256 digest for SQLite storage, and presents the raw token string once in an interactive modal with a copy button.
4. Error Handling & Session Recovery
- HTTP 401 Interception: When a session expires or credentials are revoked, the client
api()helper automatically transitions to the login view (renderLoginPage()). - Input Validation: Modals enforce client-side form validation before submitting requests to the backend.
- Graceful Error Alerts: Backend API error messages are formatted clearly in alert dialogs.