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

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

1. One feature = one directory. Never scatter a feature across layers.
2. Slices and components never import each other's internals.
3. Shared code lives in an explicit shared/ module — infrastructure and config only.
4. New feature = new directory + register route or component. Nothing else changes.
5. Delete a feature = delete its directory. If other code breaks, the boundary leaked.
6. Handlers and components stay thin — delegate to services or state logic.
7. Each slice or component owns its tests.
8. Domain models are the source of truth; DTOs exist for the boundary.
9. Start with one crate. Split to workspace only when compile times or team size demand it.
10. 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

Cross-References