v0.25.1

docs/ARCHITECTURE.md

@@ -39,6 +39,22 @@ committed document at startup; this is not one cross-memory/SQLite transaction.
 | `runtime` | Shared process state, snapshot updates, admission limits and tunnel tracking |
 | `demo` | A separate opt-in demonstration backend with its own listener |
 
+### Rust source organization
+
+Rust modules are kept as small responsibility-oriented files. Every checked-in `.rs` file
+is limited to **500 lines**; `scripts/rust_module_contracts.py` enforces the limit across
+the repository. Large logical modules use a thin facade (`config.rs`, `docker.rs`,
+`server.rs`, `runtime.rs`, `balance.rs`, `prometheus.rs`, and similar) plus files in a
+matching directory. `web_server` uses the standard `web_server/mod.rs` facade with
+submodules for configuration, filesystem confinement, responses, routing, FastCGI and
+`.htaccess`.
+
+Unit-test implementations are not embedded in production source files. They live in
+`tests.rs` or `tests/` files and are included or declared only behind `#[cfg(test)]`.
+Source-level CI also checks `include!` targets, balanced split fragments and dangling
+attributes/doc comments. This prevents a file boundary from separating `#[derive]`,
+`#[test]` or documentation from the Rust item it belongs to.
+
 Docker discovery is an optional provider boundary implemented through the standalone
 `docker-agent/`; the RustProxy process never opens the Docker socket. Cloudflare Tunnel
 remains a future module. Certbot-based HTTP-01/Cloudflare DNS/OVH DNS/RFC2136 issuance and managed renewal are optional