# Project Layout

Read this document when creating or reorganizing modules. The layout below
reflects the current package; sections marked planned describe later test and
integration work only.

## Target project layout

The repository has one Cargo package with a binary (`src/main.rs`) and a
library (`src/lib.rs`). Startup and process exit remain in `main.rs`; testable
application logic and the management TUI are library modules. A library target
does not require publishing a separate library package. Introduce a workspace
only when independently reusable or separately built components justify it.

Implemented modules include the following. Add modules as implementation
requires them; do not generate empty scaffolding for future integration work.

```text
Cargo.toml
Cargo.lock
rust-toolchain.toml
AGENTS.md
CONTEXT.md
PLANS.md
README.md
.gitignore
src/
  main.rs                  # Startup, arguments, process exit
  lib.rs                   # Module declarations and application API
  config.rs                # Application settings and path resolution
  domain.rs                # Clients, identities, address allocation/reservations, change states
  app.rs                   # Application operations and orchestration
  app/
    draft.rs               # Coordinated in-memory document, client-state, and vault drafts
    commit.rs              # Prepare, backup, install, and publish saved-state Commit
    restore.rs             # Bound preview and confirmed saved-state replacement
    backups.rs             # Manual/pre-operation backup and archive-list scenarios
  wireguard.rs             # Server configuration module boundary
  wireguard/
    document.rs            # Parsing and edits preserving original text
    metadata.rs            # Managed client comment blocks
  vault.rs                 # Encryption, import, secret retrieval
  backup.rs                # Backup archives and restoration
  runtime.rs               # Running WireGuard interface and statistics
  service.rs               # Systemd operations and restart verification
  delivery.rs              # Client configuration files and QR generation
  tui.rs                   # Terminal UI entry point
  tui/
    state.rs               # Screen state and navigation
    events.rs              # Keyboard and background events
    forms.rs               # Short-lived forms and secret owners
    render.rs              # Rendering
    terminal.rs            # Terminal setup and cleanup
tests/
  config_preservation.rs   # Untouched server configuration remains identical
  commit_restore.rs        # Persistence, backups, restore, runtime isolation
  client_delivery.rs       # Client file delivery and lifecycle workflows
  vault_import.rs          # Existing-client import and reconciliation workflows
  tui_workflow.rs          # Synthetic worker-level TUI workflows
  fixtures/                # Synthetic configuration and archive inputs
  support/
    mod.rs                 # Shared test adapters and helpers
config/
  wireguard-admin.example.toml  # Safe example; settings format chosen at implementation
docs/
  SPEC.md
  IMPLEMENTATION.md
  adr/
target/                    # Cargo output; never commit
```

- Use modules named for their responsibility. Avoid catch-all `utils`, `helpers`, or `common` modules; place supporting code with its owner.
- Begin with a single module file and split into child modules when needed. Prefer `name.rs` with `name/child.rs` for production modules; `tests/support/mod.rs` keeps test helpers from becoming a separate integration test target.
- Declare application modules once in the library, rather than duplicating them in both `main.rs` and `lib.rs`. Keep internals private or `pub(crate)`; expose only the library API needed by the binary and behavioral integration tests.
- Keep focused unit tests beside their modules under `#[cfg(test)]`; put cross-module behavioral tests in `tests/`. Use `tests/support/` for test-only adapters rather than exporting test infrastructure from the production library.
- The `config/` directory contains distributable examples, not live settings. The example filename above is illustrative and does not settle the settings format. Actual settings remain alongside the deployed executable as specified.
- Keep live server configurations, private keys, delivered client files, and runtime `Backup/` data out of the source tree and version control. Ignore generated build output and local deployment data without hiding synthetic fixtures.
- Add `examples/` only for runnable Rust examples and `benches/` only when benchmarks are needed. Do not add empty directories or scripts that duplicate Cargo commands.
- Keep the layout aligned with actual module responsibilities as the code grows. Update this section when files move; do not preserve obsolete paths merely to match the initial tree.