# 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 persistent `localStorage` preference. - **Responsive Layout**: Mobile-first responsive layout with side-drawer navigation and `@media (max-width: 768px)` breakpoints. - **Live WebSocket Event Stream**: Connects to `ws:///api/v1/ws` authenticated via the browser's `nx9_session` HttpOnly cookie for 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 with explicit **Role** badges (`Overlay` vs `Upstream`), "+ Create Interface" modal with tabbed **Standard Overlay** vs **Import Upstream VPN** (`.conf` parser & live preview), interface **Edit** action (preserves private/public key identity), **Restart** action (link teardown + re-sync), enable/disable toggle, delete action (protected against `wg0`), `Auto (Dynamic)` listen port display, and embedded read-only CLI console. | | `#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 subsystems (`system`, `network`, `wan`, `wireguard`, `peer`, `routing`, `forwarding`, `firewall`, `nat`, `mtu`, `reconciliation`) with remediation hints. | | `#live-state` | **Live State** | Live Linux Netlink kernel telemetry, active WireGuard interfaces, and live routing table entries. | | `#settings` | **Settings** | Dedicated **WireGuard Server Endpoint** configuration card (Host, Port, Enabled toggle, live preview, save), appliance 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 & Upstream Workflows ### 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 When opening the export modal for a peer, the UI automatically: 1. Pre-populates the **Server Endpoint** field using the persistent settings (`wireguard.server_host` and `wireguard.server_port`) configured under Settings. 2. Displays a `"Default from Server Settings"` badge indicating persistent configuration source. 3. Automatically triggers client `.conf` and QR code generation on modal open without requiring manual typing. 4. Allows the administrator to enter a temporary one-off endpoint override directly in the modal for specialized network requirements without mutating global server settings. 5. Displays both: - **Interactive Vector QR Code**: Inline SVG rendering for scanning directly with the official WireGuard mobile app. - **Downloadable `.conf` File**: Standard WireGuard client configuration file formatted for instant download or clipboard copy. ### C. Third-Party Upstream Import Modal (`#interfaces`) The "+ Create Interface" modal provides a dedicated **Import Upstream VPN** tab: 1. Accepts interface name (e.g. `proton0`) and raw `.conf` content from third-party VPN providers (e.g. ProtonVPN). 2. Provides a **Preview Configuration** button triggering `/api/v1/interfaces/upstreams/preview` to dry-run validate the configuration and display parsed tunnel addresses, DNS, MTU, listen port (showing `Auto (Dynamic)` when omitted), and provider peer details before writing to SQLite. 3. Secret redaction: Private keys and PSKs are never echoed back in preview responses or displayed in cleartext in the UI. 4. On submission, atomically saves desired state, provisions the kernel interface, and triggers reconciliation. ### D. Embedded Read-Only CLI Console (`#interfaces`) Provides an in-browser interactive terminal to execute read-only operational and status commands (e.g., `nx9-wg interface upstream list`, `nx9-wg diagnostics all`). Enforces a strict server-side command allowlist and output secret sanitizer. ### E. 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.