Add Codex specific files

2026-10-18 21:33:52 +03:00
parent 86dbead893
commit 7b475bfcc8
13 changed files with 652 additions and 0 deletions
@@ -0,0 +1,63 @@
+# 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.
+
+```text
+Cargo.toml
+Cargo.lock
+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.