# NX9 WireGuard Architecture Blueprint

## System Overview

`nx9-wg` is structured as a modular Rust workspace consisting of six specialized crates and a root binary.

| Crate | Responsibility | Dependencies |
| :--- | :--- | :--- |
| **`nx9-wg-core`** | Domain entities, cryptographic utilities (Argon2id, x25519, SHA-256), data validation, and configuration types. | `serde`, `argon2`, `x25519-dalek`, `sha2`, `ipnet`, `chrono`, `uuid` |
| **`nx9-wg-db`** | Authoritative persistence layer using SQLite with WAL mode, automated migrations, and isolated repository modules. | `nx9-wg-core`, `sqlx` (sqlite) |
| **`nx9-wireguard`**| WireGuard interface controller, client `.conf` configuration builder, live telemetry inspection, and pure Rust QR engine. | `nx9-wg-core`, `qrcode`, `image`, `base64` |
| **`nx9-wg-network`** | Linux kernel IP forwarding, routing table synchronization, and atomic `inet nx9_wg` nftables ruleset generator. | `nx9-wg-core`, `ipnet` |
| **`nx9-wg-api`** | Axum REST API, session and token authentication middleware, WebSocket live event broadcast, and Reconciliation Engine. | `nx9-wg-core`, `nx9-wg-db`, `nx9-wireguard`, `nx9-wg-network`, `axum`, `tower` |
| **`nx9-wg-ui`** | Dioxus web client shell (client only, business logic isolated in backend). | `nx9-wg-core` |
| **`nx9-wg`** | Primary application binary providing CLI operations and HTTP daemon server. | All workspace crates, `clap` |

---

## Architectural Invariants

1. **Strict SQL Isolation**: All raw SQL queries and SQLite interactions are confined entirely to `crates/nx9-wg-db/`. No other crate or handler interacts with SQLite directly.
2. **Zero Shelling Out**: WireGuard, routing, and packet filtering interact with kernel abstractions and netlink without executing `wg`, `wg-quick`, or `iptables` subprocesses.
3. **Single Administrator Model**: The system maintains exactly one administrative identity with `CHECK (id = 1)`. No RBAC, multi-tenant, or organization complexity is introduced.
4. **Secret Redaction**: Passwords, private keys, preshared keys, and API tokens are never logged, persisted in plaintext, or exposed in error messages. All secret wrapper types implement custom `Debug` redactions (`[REDACTED]`).
5. **Deterministic Reconciliation**: Desired state in SQLite is the single source of truth. The reconciler computes drift and idempotently applies adjustments without touching unmanaged Linux resources.