nx9-wg/docs/UI.md

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://<host>/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.