# Development and Contributing Guide

## Environment Setup

- **Rust Toolchain**: `rustc` and `cargo` 1.85+ (Edition 2024).
- **SQLite3 development headers** (for `sqlx-sqlite`).

---

## Workspace Structure

```
.
├── Cargo.toml
├── Cargo.lock
├── config.example.toml
├── nx9-wg.service
├── Dockerfile
├── src/
│   └── main.rs
├── crates/
│   ├── nx9-core/         # Domain models, crypto, config, validation
│   ├── nx9-db/           # SQLite schema, migrations, repositories
│   ├── nx9-wireguard/    # WireGuard controller, .conf builder, QR engine
│   ├── nx9-network/      # Forwarding, routing, nftables
│   ├── nx9-api/          # Axum API, WebSocket, Reconciler, Backup
│   └── nx9-ui/           # Dioxus UI shell
└── docs/                 # Documentation suite
```

---

## Running Quality Gates

Before submitting changes, all mandatory quality gates must pass:

```bash
# 1. Format check
cargo fmt --all -- --check

# 2. Workspace check
cargo check --workspace

# 3. Unit and integration tests
cargo test --workspace

# 4. Strict clippy with warnings denied
cargo clippy --workspace --all-targets --all-features -- -D warnings

# 5. Marker scan
git grep -n -E 'TODO|FIXME|XXX|HACK|unimplemented!|todo!|panic!' src/ crates/
```