Clean up documentation structure and links

2026-08-30 20:02:38 +05:30
1 parent d25846c58c
commit 32a325234a
@@ -0,0 +1,82 @@
+# Developer Guide & Repository Reference
+
+This guide provides instructions for building, testing, linting, and contributing to the `nx9-wg` codebase.
+
+---
+
+## 1. Workspace Layout
+
+The repository is organized as a Cargo workspace containing 6 crates and the root application binary:
+
+- **`crates/nx9-wg-core`**: Common domain entities, RFC validators, cryptography, and configuration.
+- **`crates/nx9-wg-db`**: SQLite database persistence layer, migration SQL scripts, and repository implementations.
+- **`crates/nx9-wireguard`**: WireGuard Generic Netlink execution, RTNETLINK link management, config builder, and QR engine.
+- **`crates/nx9-wg-network`**: RTNETLINK route management, `libnftables.so.1` integration, and procfs forwarding.
+- **`crates/nx9-wg-api`**: Axum REST API router, WebSocket broadcaster, authentication middleware, and reconciliation engine.
+- **`crates/nx9-wg-ui`**: Design tokens, CSS stylesheet compiler, view models, and SPA asset integration.
+- **`src/main.rs`**: Root CLI command parser and daemon entry point.
+
+---
+
+## 2. Prerequisites & Build Commands
+
+### Prerequisites
+- **Rust Toolchain**: 1.85+ (Edition 2024).
+- **C Compiler**: `gcc` or `clang` (for SQLite C amalgamation).
+- **Linux Libraries**: `libnftables-dev` (Debian/Ubuntu) or `nftables-devel` / `libnftables` (Fedora/Arch).
+
+### Build Commands
+```bash
+# Debug build
+cargo build --workspace
+
+# Release build
+cargo build --release
+
+# Format check
+cargo fmt --all -- --check
+
+# Clippy linter
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+---
+
+## 3. Test Execution & SAFE Mode (`LIVE=0`) vs Privileged Mode (`LIVE=1`)
+
+To prevent accidental modifications to developer workstations, all integration and live kernel test scripts default to SAFE mode (`LIVE=0`):
+
+```bash
+# 1. Run full workspace unit & integration tests
+cargo test --workspace
+
+# 2. Run Comprehensive CLI Verification Suite (210 checks)
+LIVE=0 bash scripts/test-cli-comprehensive.sh
+
+# 3. Run Native Linux Integration Test Suite (20 checks)
+LIVE=0 bash scripts/test-native-integration.sh
+
+# 4. Run Dedicated Live Kernel Test Suite (24 checks)
+LIVE=0 bash scripts/test-live-kernel.sh
+```
+
+### Privileged Real-Kernel Testing (`LIVE=1`)
+> [!CAUTION]
+> `LIVE=1` tests must ONLY be executed on a dedicated disposable Linux virtual machine or container with `CAP_NET_ADMIN`. Never execute `LIVE=1` on a production host.
+
+```bash
+# On a dedicated disposable VM as root:
+sudo LIVE=1 bash scripts/test-live-kernel.sh
+```
+
+---
+
+## 4. Release Packaging
+
+To build the self-contained release distribution archives:
+
+```bash
+bash scripts/package-release.sh
+```
+
+Outputs `.tar.gz`, `.tar.xz`, and `.sha256` files in `target/dist/`.