wireguard-admin/docs/PROJECT_LAYOUT.md

Project Layout

This is the integrated package layout after M26. Paths below exist in the repository; scenario descriptions name current owners. Add modules when a cohesive responsibility needs them, not as placeholders.

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 TUI are library modules. The library target is not a separately published package.

Cargo.toml
Cargo.lock
rust-toolchain.toml
AGENTS.md
CONTEXT.md
PLANS.md
README.md
src/
  main.rs                  # Startup, arguments, process exit
  lib.rs                   # Library modules; test-only container driver gate
  startup.rs               # Root boundary, settings/store loading, session entry
  config.rs                # Settings validation and executable-relative paths
  domain.rs                # Client projection, address allocation/reservations, apply knowledge
  app.rs                   # Application facade, session, and public operation types
  app/
    draft.rs               # Coordinated document/client/vault draft replacements
    first_delivery.rs      # Session-local one-use capability and retry state
    first_file.rs          # First-delivery file and optional QR scenario
    reissue.rs             # Password-per-action saved-client reissue
    read_model.rs          # Secret-free application facts and per-action eligibility
    commit.rs              # Backup, saved install, and Commit publication
    restore.rs              # Preview, reservation rebuild, and confirmed saved replacement
    backups.rs              # Manual/pre-operation backup and archive listing
    restart.rs              # Restart preview, backup/job/verify/publication sequence
  wireguard.rs             # Server configuration module boundary
  wireguard/
    document.rs             # Lossless parse, peer inspection and document authority
    edit.rs                 # Byte-preserving peer and metadata edits
    metadata.rs             # Managed comment grammar and metadata validation
  vault.rs                  # Vault format, encryption, key matching and retrieval
  vault/
    source.rs               # Read-only configured client-source access
    import.rs               # Client-file reconciliation and encrypted import
  persistence.rs             # Saved-file installation, recovery and state codec
  backup.rs                  # Versioned archive encoding, parsing and preview
  runtime.rs                 # Runtime observations, peer projections and comparison
  runtime/
    netlink.rs               # Bounded Generic Netlink WireGuard reader
    transport.rs             # Read-only runtime transport
  service.rs                 # Systemd request and job completion adapter
  service/
    dbus.rs                  # D-Bus systemd implementation
  delivery.rs                # Client configuration rendering and adapter boundary
  delivery/
    files.rs                 # Secure client file publication
    qr.rs                    # Terminal QR generation
  tui.rs                     # TUI entry and session lifecycle
  tui/
    state.rs                 # Screens, selection, UI generations and navigation
    events.rs                # Typed commands, worker queue and lifecycle
    events/
      executor.rs            # Application command adaptation and prepared contexts
    forms.rs                 # Short-lived form inputs and sensitive commands
    render.rs                # Visual strings, styles, wrapping and layout
    terminal.rs              # Terminal setup, event loop and cleanup
  container_driver.rs        # Test-only Alpine scenario driver (`cfg(test)`)
tests/
  config_preservation.rs     # Synthetic byte-preservation behavior
  commit_restore.rs          # Persistence, backups, restore and runtime isolation
  client_delivery.rs         # First delivery, retry, reissue and lifecycle behavior
  runtime_restart.rs         # Restart scenario behavior using controlled adapters
  vault_import.rs            # Import and reconciliation behavior
  tui_workflow.rs            # Worker-level TUI workflows and synthetic PTY checks
  testcontainers_wireguard.rs # Explicitly selected, ignored Alpine integration suite
  support/                   # Shared fixtures, adapters and container harness
  fixtures/wireguard/        # Synthetic server configuration
  containers/alpine/         # Pinned Alpine runtime image and readiness support
  vm/                        # Guarded disposable-VM preparation/test scripts
config/
  wireguard-admin.example.toml # Safe distributable example settings
docs/
  SPEC.md
  PROJECT_LAYOUT.md
  architecture/domain-refactoring.md
  adr/
target/                      # Cargo output; never commit

Ownership rules

• Application is the public facade. Scenario ordering belongs in src/app/ owners; the facade delegates without transferring authority to the TUI.
• The server ConfigDocument is authoritative for peers and metadata. ClientStates is only the manageable-client projection. Editing preserves unowned bytes and comments.
• Domain logic does not perform file, crypto, runtime, service, or rendering work. Persistence owns installed state; backup owns archive encoding; runtime owns observations/comparison; service owns systemd calls.
• app/read_model.rs supplies secret-free facts and action eligibility. TUI state owns selection/navigation/generation; the executor binds prepared continuations and calls application operations; renderers own presentation.
• Keep module internals private or pub(crate) where possible. Public facade APIs retained for integration fixture setup are documented with their caller audit in the architecture map.
• Keep focused unit tests beside their modules and cross-module behavior in tests/. src/container_driver.rs is included only in the library test harness. Its opt-in Alpine application fixture is not systemd acceptance.
• config/ holds safe examples, not live settings. Runtime data and archives remain outside the source tree. Do not commit live configuration, keys, delivered client files, or generated Backup/ data.
• Keep this map aligned with actual files and responsibility. Do not add empty directories or speculative traits/modules.