Clean up documentation structure and links

docs/DESIGN-PRINCIPLES.md

@@ -0,0 +1,82 @@
+# NX9 WireGuard — Architectural & Design Principles
+
+> **"Sovereign, self-hosted, Linux-native network infrastructure built from first principles."**
+
+---
+
+## 1. The NX9 Philosophy
+
+`nx9-wg` was conceived as a clean, high-performance, single-binary WireGuard appliance and network management engine for sovereign infrastructure. It is built upon the following foundational principles:
+
+### A. Self-Hosted First & Full Ownership
+Network infrastructure is a critical sovereignty boundary. Administrators must have complete, unencumbered ownership of their cryptographic keys, network routing policies, and configuration data. `nx9-wg` operates entirely locally without phone-home telemetry, cloud dependencies, or external licensing servers.
+
+### B. Linux-Native Architecture
+Rather than treating the Linux kernel as an opaque black box accessed via shell utilities, `nx9-wg` communicates directly with kernel networking subsystems using native Netlink protocols (RTNETLINK and WireGuard Generic Netlink) and direct `/proc` interfaces.
+
+### C. FOSS & No Vendor Lock-In
+`nx9-wg` is free and open-source software dual-licensed under `MIT OR Apache-2.0`. All database schemas, configuration formats, cryptographic profiles, and backup archives use open, standard specifications (SQLite, TOML, JSON, Base64).
+
+### D. Zero Scripting Runtime Dependencies
+The entire application—from the HTTP/WebSocket API server and reactive SPA frontend to cryptographic key generation, QR rendering, database migrations, and kernel Netlink communication—is compiled into a single native Rust binary. There is zero runtime dependency on Node.js, npm, Electron, Python, or external shell scripts.
+
+### E. CLI-First & Headless Operational Simplicity
+Every capability exposed by the Web UI or REST API is first available as a first-class native CLI command supporting human-readable tables as well as machine-readable JSON, YAML, and CSV formats.
+
+---
+
+## 2. Why Not an Imperative Shell Wrapper?
+
+Many existing WireGuard management tools act merely as thin Web UI wrappers around command-line utilities like `wg`, `wg-quick`, `iptables`, and `ip`. This model introduces severe architectural limitations:
+
+1. **Fragile Process Spawning**: Shelling out to external executables (`std::process::Command`) incurs substantial overhead, introduces quoting/injection risks, and parses fragile string outputs that break across operating system versions.
+2. **Lack of Authoritative State**: Relying on `/etc/wireguard/wg0.conf` text files makes atomic transactional updates, relational constraints, foreign keys, and audit logging difficult and error-prone.
+3. **Configuration Drift**: Imperative changes applied directly to the kernel or configuration files easily drift out of sync with what the web management interface displays.
+4. **Host Network Destruction**: Script-based firewall and routing flush commands (e.g., `iptables -F` or modifying default routing tables) often disrupt container engines (Docker, Podman), hypervisors (KVM, libvirt), or host networking.
+
+---
+
+## 3. Core Architectural Invariants
+
+### 1. SQLite Desired-State Authority
+The SQLite database is the single authoritative source of truth for all intended configuration state (interfaces, peers, networks, routes, firewall rules, and NAT policies). The kernel execution plane is a cache that is brought into alignment through continuous, deterministic reconciliation.
+
+### 2. Zero Subprocess Execution Guarantee
+Production Rust code in `nx9-wg` is strictly forbidden from invoking `std::process::Command` or `tokio::process`. All kernel mutations occur via in-process Netlink sockets or `libnftables` Netfilter bindings.
+
+### 3. Strict Resource Ownership & Scoping
+- **Firewall Rules**: Confined strictly to `table inet nx9_wg`. External tables created by Docker, Kubernetes, or host firewalls are never modified or flushed.
+- **Routing**: `nx9-wg` manages only routes explicitly defined in its database or attached to its managed interfaces. Default gateway routes and unmanaged host routes are never altered.
+
+### 4. Single Administrator Security Model
+`nx9-wg` avoids complex RBAC frameworks in favor of a strictly enforced single-administrator model locked by database constraints (`CHECK (id = 1)`). This eliminates privilege escalation, role confusion, and broken object-level authorization vulnerabilities.
+
+### 5. Multi-Cycle Idempotent Reconciliation
+State reconciliation follows a deterministic, read-only plan phase followed by a serialized apply phase and post-apply verification. Repeated executions against an already converged system produce zero mutations (NOOP).
+
+---
+
+## 4. Architectural Summary
+
+```
+ ┌────────────────────────────────────────────────────────┐
+ │            Single Administrator (Web UI / CLI)         │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+ ┌───────────────────────────▼────────────────────────────┐
+ │               Axum REST API & WebSockets               │
+ └───────────────────────────┬────────────────────────────┘
+                             │
+ ┌───────────────────────────▼────────────────────────────┐
+ │         Authoritative SQLite Desired State (WAL)       │
+ └───────────────────────────┬────────────────────────────┘
+                             │ (Periodic / Triggered)
+ ┌───────────────────────────▼────────────────────────────┐
+ │                 Reconciliation Engine                  │
+ └───────┬───────────────────┼───────────────────┬────────┘
+         │ (RTNETLINK/Genl)  │ (libnftables)     │ (Procfs)
+ ┌───────▼───────┐   ┌───────▼───────┐   ┌───────▼───────┐
+ │ WireGuard Genl│   │ inet nx9_wg   │   │ IP Forwarding │
+ │ Kernel Socket │   │ Table Filter  │   │  /proc/sys    │
+ └───────────────┘   └───────────────┘   └───────────────┘
+```