wireguard-admin/docs/PROJECT_LAYOUT.md

Project Layout

Read this document when creating or reorganizing modules. The paths below are planned until implemented.

Target project layout

Start with one Cargo package containing a binary (src/main.rs) and a library (src/lib.rs). Keep startup, argument handling, and process exit in main.rs; place testable application logic in 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.

The following is the intended layout, not a claim that these files already exist. Create modules and directories as implementation requires them; do not generate empty scaffolding for the entire tree.

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, change states
  app.rs                   # Application operations and orchestration
  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
    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_lifecycle.rs      # Import, creation, delivery, deletion, state transitions
  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.