Architecture & Design Highlights Summary

Every highlight bullet from the 11 pages in this section, gathered on one page and grouped by the page it came from.

Architecting Rust Systems

• The crate/module graph is not documentation of the architecture, it is the architecture.
• Error strategy decided on day one prevents anyhow from spreading into every layer.
• Newtypes and enums-as-state-machines turn business rules into compiler checks.
• The borrow checker rewards architectures with clear ownership; it punishes tangled ones.

Architecture Decision Checklist

• Pin Rust 1.97.0 and edition 2024 in rust-toolchain.toml
• Commit Cargo.lock for applications to ensure consistent builds
• Keep domain crates pure, without HTTP or SQLx imports
• Use thiserror for domain errors and map them to HTTP in the API crate
• Implement graceful shutdown with SIGTERM handling and a drain timeout
• Deploy release binaries in minimal containers or as static executables

Workspace & Crate Boundaries

• Split workspaces for pure domain logic and thin binaries
• Domain crates should not depend on application-specific code
• Run domain tests fast without network dependencies
• Extract crates when compile time hurts or boundaries are stable
• Avoid circular path dependencies by extracting shared types
• Use 3-7 crates; more requires a platform team

Error Strategy

• Use precise domain enums for layer errors
• Map transport errors at the edges of your application
• Aggregate context in binaries, not libraries
• Map infrastructure errors at the repository boundary
• Use #[non_exhaustive] on public error enums
• Avoid anyhow in libraries; use it for startup errors

Trait-Based Abstraction

• Define port traits in the domain and implement adapters in the infrastructure
• Use traits for external I/O boundaries and multiple implementations
• Employ Send + Sync bounds for Tokio handlers with trait objects
• Prefer generics in core and dyn at the edge to avoid vtable costs
• Split large "God traits" into smaller, focused Reader/Writer traits
• Extract a trait when a second implementation becomes necessary

Domain Modeling with Types

• Use enums, newtypes, and typestate to prevent invalid domain combinations
• Implement methods on domain types, not anemic structs
• Avoid bool flags for state; use enums instead
• Map Serde DTOs to rich domain types at the boundary
• Use NonEmpty crates for at-least-one collection invariants

Configuration & Feature Design

• Separate compile-time Cargo features from runtime configuration
• Load settings once at startup with validation
• Use the config crate to layer configuration files
• Avoid runtime feature flags as Cargo features; use runtime config
• Never put secrets in default.toml; use environment variables
• Group features like "full" and "minimal" to avoid feature explosion

Refactoring Decisions

• Apply refactoring when compile times hurt or boundaries blur
• Extract domain types and rules to a dedicated crate
• Break circular dependencies using ports traits in the domain
• Replace unwrap layers with typed errors for predictable failures
• Migrate async incrementally using Axum and Tokio
• Split large error enums into per-context enums for clarity

Codebase Audit Checklist

• Score unchecked items as debt with severity
• Run this checklist quarterly on production services
• Ensure rust-toolchain.toml matches CI version 1.97.0
• Keep handlers under 50 lines or extract services
• Validate configuration at application startup
• Document runbooks and link them from the README

Migrating from C/C++ to Rust

• Migrate incrementally using FFI boundaries, rewriting modules in Rust
• Generate bindings with bindgen for C APIs, cbindgen for Rust modules
• Link with CMake/build.rs and run existing C tests against Rust
• Avoid big bang rewrites; use the strangler fig pattern
• Document ownership for allocators to prevent mismatches across FFI
• Use repr(C) and tests to prevent implicit union/enum layout ABI breaks

Architecture Best Practices

• Domain crate without framework imports
• Thin handlers and typed errors
• Workspace dependency alignment
• ADRs for major forks