Architecture
Core Question
How should this project's modules, boundaries, and data flow
be organized so that adding a feature means changing one place?
The right architecture makes features independently addable,
deletable, and testable. The wrong one scatters a single change
across the entire codebase.
Quick Decisions
| Situation |
Reach For |
Why |
| Web API with distinct features |
Vertical Slice Architecture |
Each feature is self-contained |
| Complex read vs write models |
VSA + CQRS variant |
Separates command and query paths within a slice |
| Large API, team-per-feature |
VSA workspace layout |
Compile-time boundaries, independent deps |
| Terminal UI with interactive views |
TUI component-based (Ratatui) |
Each component owns state, rendering, input |
| TUI app with business logic / data layers |
TUI components + vertical slices |
Feature slices own their components, services, and models |
| Feature needs data from another |
Cross-slice communication |
Pick the lightest strategy that works |
| Custom request validation |
Axum extractor (FromRequestParts) |
Compile-time enforced, reusable across handlers |
| Per-request context (user, tenant, correlation ID) |
RequestContext extractor |
Single struct, extracted once, threaded through layers |
| Simple middleware (logging, auth) |
axum::middleware::from_fn |
Minimal boilerplate, async-friendly |
| Middleware ordering |
outermost = first executed |
CORS and tracing before auth, auth before handlers |
| Shared state (DB pool, config) |
State<AppState> with FromRef |
Compile-time checked, no runtime downcasting |
| Route-specific auth |
.route_layer(middleware::from_fn(require_auth)) |
Protects only routes in that group |
| Request/response transformation |
Tower Layer implementation |
Full control over Service wrapping |
| Project has < 10 source files |
Don't architect — flat structure |
See rust-quality → Quick Decisions |
Architecture Selection
Start with the application type:
- Web API → Vertical slices. Single crate for < 15 features,
workspace for more. If reads and writes have very different shapes,
add CQRS within the slice.
- Terminal UI → Component-based. Each screen or widget is a
component with init/update/draw. If the app has data persistence
or distinct feature domains, combine with vertical slices — each
feature owns its components alongside service/model/repository.
- Library → Feature-based modules. See rust-quality for module
organization patterns.
- CLI tool → Flat or feature-based depending on size. See
rust-quality for thresholds.
Then consider domain complexity:
- Simple CRUD → Standard VSA slice (handler, service, model,
repository, dto, routes, tests).
- Complex domain logic → VSA + CQRS commands/queries within
each slice.
- Rich domain model → DDD building blocks within VSA slices.
See rust-ddd skill for aggregates, value objects, events,
repository separation.
Key Rules
- One feature = one directory. Never scatter a feature across layers.
- Slices and components never import each other's internals.
- Shared code lives in an explicit
shared/ module — infrastructure and config only.
- New feature = new directory + register route or component. Nothing else changes.
- Delete a feature = delete its directory. If other code breaks, the boundary leaked.
- Handlers and components stay thin — delegate to services or state logic.
- Each slice or component owns its tests.
- Domain models are the source of truth; DTOs exist for the boundary.
- Start with one crate. Split to workspace only when compile times or team size demand it.
- When in doubt, duplicate between slices rather than coupling them with a shared abstraction.
Usage Scenarios
Scenario 1: "I'm building a new web API with Axum"
→ Start with VSA single-crate layout. Create features/ with one
directory per resource. Wire routes in router.rs, shared
infrastructure in shared/.
Scenario 2: "Feature A needs to read data from Feature B"
→ Check cross-slice communication strategies. For display: use a
read model (SQL JOIN). For business logic: use a public API trait.
For async reactions: domain events.
Scenario 3: "I'm building a terminal UI with Ratatui"
→ Use the component-based structure. Each component implements
the Component trait with init/handle_events/update/draw. If the
app has data layers or multiple feature domains, combine with
vertical slices — each feature owns its components + service + model.
Scenario 4: "My web API has 20+ features and builds are slow"
→ Graduate to VSA workspace layout. One crate per feature, shared
crate for infrastructure. Inherit dependencies and lints from
workspace root.
Scenario 5: "My handler knows the authenticated user but my
repository doesn't"
→ Define a RequestContext struct in shared/context.rs, extract
it via FromRequestParts, pass &ctx to services and repository
methods. See references/request-context.md.
Reference Index
| Reference |
Read When |
| references/vertical-slices.md |
Setting up a web API: slice structure, file responsibilities, root wiring, CQRS variant, workspace layout, shared infrastructure, common dependencies |
| references/cross-slice.md |
One feature needs data or behavior from another: 4 strategies (API traits, read models, shared types, domain events) with decision guide |
| references/tui-components.md |
Building a Ratatui TUI: component trait, file structure, app loop, state management |
| references/web-middleware.md |
Axum extractors (ordering, custom, rejection), tower middleware (from_fn, Layer, ordering), State vs Extension, auth patterns, CORS/compression/rate-limiting |
| references/request-context.md |
Threading per-request identity through layers: RequestContext struct, extractor, context-aware repository traits, tenant scoping, audit logging, tracing integration |
| rust-ddd skill |
Rich domain models within slices: aggregates, value objects, domain events, repository separation. Use when domain complexity warrants DDD building blocks |
Cross-References
| When |
Check |
| Cargo.toml defaults, workspace setup, module organization basics |
rust-quality → Quick Decisions |
| Async handler patterns, tokio runtime in web APIs |
rust-async → Quick Decisions |
| Error type design for shared error module |
rust-errors → Quick Decisions |
| Trait design for service boundaries and API traits |
rust-types → Quick Decisions |
| Public API design within slices, naming conventions |
rust-api → Quick Decisions |
| Rich domain model, aggregates, value objects, events |
rust-ddd → Quick Decisions |
| Request tracing middleware, correlation IDs |
rust-tracing → Quick Decisions |
| Rejection/error responses from extractors |
rust-errors → Quick Decisions |
1---2name: rust-architecture3description: Rust project architecture patterns — vertical slice architecture for web APIs, component-based TUI structure for Ratatui apps, and cross-feature communication strategies. Use when organizing features into slices, wiring routes and services, choosing how features communicate, structuring a Ratatui terminal application, or deciding between single-crate and workspace layouts. Also use when setting up a new Axum/Actix-web project structure or adding a new feature to an existing sliced codebase.4---56# Architecture78## Core Question910**How should this project's modules, boundaries, and data flow11be organized so that adding a feature means changing one place?**1213The right architecture makes features independently addable,14deletable, and testable. The wrong one scatters a single change15across the entire codebase.1617---1819## Quick Decisions2021| Situation | Reach For | Why |22|-----------|-----------|-----|23| Web API with distinct features | Vertical Slice Architecture | Each feature is self-contained |24| Complex read vs write models | VSA + CQRS variant | Separates command and query paths within a slice |25| Large API, team-per-feature | VSA workspace layout | Compile-time boundaries, independent deps |26| Terminal UI with interactive views | TUI component-based (Ratatui) | Each component owns state, rendering, input |27| TUI app with business logic / data layers | TUI components + vertical slices | Feature slices own their components, services, and models |28| Feature needs data from another | Cross-slice communication | Pick the lightest strategy that works |29| Custom request validation | Axum extractor (`FromRequestParts`) | Compile-time enforced, reusable across handlers |30| Per-request context (user, tenant, correlation ID) | `RequestContext` extractor | Single struct, extracted once, threaded through layers |31| Simple middleware (logging, auth) | `axum::middleware::from_fn` | Minimal boilerplate, async-friendly |32| Middleware ordering | outermost = first executed | CORS and tracing before auth, auth before handlers |33| Shared state (DB pool, config) | `State<AppState>` with `FromRef` | Compile-time checked, no runtime downcasting |34| Route-specific auth | `.route_layer(middleware::from_fn(require_auth))` | Protects only routes in that group |35| Request/response transformation | Tower `Layer` implementation | Full control over Service wrapping |36| Project has < 10 source files | Don't architect — flat structure | See rust-quality → Quick Decisions |3738---3940## Architecture Selection4142Start with the application type:4344- **Web API** → Vertical slices. Single crate for < 15 features,45 workspace for more. If reads and writes have very different shapes,46 add CQRS within the slice.47- **Terminal UI** → Component-based. Each screen or widget is a48 component with init/update/draw. If the app has data persistence49 or distinct feature domains, combine with vertical slices — each50 feature owns its components alongside service/model/repository.51- **Library** → Feature-based modules. See rust-quality for module52 organization patterns.53- **CLI tool** → Flat or feature-based depending on size. See54 rust-quality for thresholds.5556Then consider domain complexity:5758- **Simple CRUD** → Standard VSA slice (handler, service, model,59 repository, dto, routes, tests).60- **Complex domain logic** → VSA + CQRS commands/queries within61 each slice.62- **Rich domain model** → DDD building blocks within VSA slices.63 See rust-ddd skill for aggregates, value objects, events,64 repository separation.6566---6768## Key Rules69701. One feature = one directory. Never scatter a feature across layers.712. Slices and components never import each other's internals.723. Shared code lives in an explicit `shared/` module — infrastructure and config only.734. New feature = new directory + register route or component. Nothing else changes.745. Delete a feature = delete its directory. If other code breaks, the boundary leaked.756. Handlers and components stay thin — delegate to services or state logic.767. Each slice or component owns its tests.778. Domain models are the source of truth; DTOs exist for the boundary.789. Start with one crate. Split to workspace only when compile times or team size demand it.7910. When in doubt, duplicate between slices rather than coupling them with a shared abstraction.8081---8283## Usage Scenarios8485**Scenario 1:** "I'm building a new web API with Axum"86→ Start with VSA single-crate layout. Create `features/` with one87directory per resource. Wire routes in `router.rs`, shared88infrastructure in `shared/`.8990**Scenario 2:** "Feature A needs to read data from Feature B"91→ Check cross-slice communication strategies. For display: use a92read model (SQL JOIN). For business logic: use a public API trait.93For async reactions: domain events.9495**Scenario 3:** "I'm building a terminal UI with Ratatui"96→ Use the component-based structure. Each component implements97the Component trait with init/handle_events/update/draw. If the98app has data layers or multiple feature domains, combine with99vertical slices — each feature owns its components + service + model.100101**Scenario 4:** "My web API has 20+ features and builds are slow"102→ Graduate to VSA workspace layout. One crate per feature, shared103crate for infrastructure. Inherit dependencies and lints from104workspace root.105106**Scenario 5:** "My handler knows the authenticated user but my107repository doesn't"108→ Define a `RequestContext` struct in `shared/context.rs`, extract109it via `FromRequestParts`, pass `&ctx` to services and repository110methods. See references/request-context.md.111112---113114## Reference Index115116| Reference | Read When |117|-----------|-----------|118| [references/vertical-slices.md](references/vertical-slices.md) | Setting up a web API: slice structure, file responsibilities, root wiring, CQRS variant, workspace layout, shared infrastructure, common dependencies |119| [references/cross-slice.md](references/cross-slice.md) | One feature needs data or behavior from another: 4 strategies (API traits, read models, shared types, domain events) with decision guide |120| [references/tui-components.md](references/tui-components.md) | Building a Ratatui TUI: component trait, file structure, app loop, state management |121| [references/web-middleware.md](references/web-middleware.md) | Axum extractors (ordering, custom, rejection), tower middleware (from_fn, Layer, ordering), State vs Extension, auth patterns, CORS/compression/rate-limiting |122| [references/request-context.md](references/request-context.md) | Threading per-request identity through layers: RequestContext struct, extractor, context-aware repository traits, tenant scoping, audit logging, tracing integration |123| rust-ddd skill | Rich domain models within slices: aggregates, value objects, domain events, repository separation. Use when domain complexity warrants DDD building blocks |124125---126127## Cross-References128129| When | Check |130|------|-------|131| Cargo.toml defaults, workspace setup, module organization basics | rust-quality → Quick Decisions |132| Async handler patterns, tokio runtime in web APIs | rust-async → Quick Decisions |133| Error type design for shared error module | rust-errors → Quick Decisions |134| Trait design for service boundaries and API traits | rust-types → Quick Decisions |135| Public API design within slices, naming conventions | rust-api → Quick Decisions |136| Rich domain model, aggregates, value objects, events | rust-ddd → Quick Decisions |137| Request tracing middleware, correlation IDs | rust-tracing → Quick Decisions |138| Rejection/error responses from extractors | rust-errors → Quick Decisions |
dawidpereira