# 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/`.