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`

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.
Zero Shelling Out: WireGuard, routing, and packet filtering interact with kernel abstractions and netlink without executing wg, wg-quick, or iptables subprocesses.
Single Administrator Model: The system maintains exactly one administrative identity with CHECK (id = 1). No RBAC, multi-tenant, or organization complexity is introduced.
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]).
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.