Domain-Driven Design

Core Question

How should this business domain be modeled so that Rust's type system and ownership enforce the rules at compile time?

DDD in Rust is not a port of Java or C#. There is no DI container, no mediator, no exception hierarchy. Rust's private fields, &mut self, newtype pattern, and exhaustive match give you compile-time enforcement that other languages achieve only through runtime discipline.

Quick Decisions

Key Principles

1. Rust is not Java/C#. No DI container (wire deps explicitly with Arc<dyn Trait>). No mediator (Axum extractors ARE DI, the Router IS the dispatcher). No exceptions (errors are Result<T, E> values).
2. Ownership IS encapsulation. Private fields on an aggregate mean outside code cannot break invariants. &mut self on command methods means one writer at a time. The compiler enforces what Java achieves with synchronized.
3. Enums are sum types, not labels. Rust enums are tagged unions — each variant can carry different data. They are the same construct as Option and Result: algebraic sum types with monadic combinators (.map(), .and_then(), ?). OrderStatus, OrderEvent, OrderError — all enums. The compiler forces exhaustive handling via match. When state determines which operations are valid, consider making the aggregate itself an enum (typestate) so invalid transitions are compile errors, not runtime Results. See references/building-blocks.md § "Enums Beyond Labels".
4. Value objects are newtypes. Never pass raw String, i64, or Uuid for domain concepts. OrderId(Uuid), Quantity(u32), Money { amount, currency } — validated at construction, zero-cost at runtime.
5. Domain models are pure. models.rs, events.rs, error.rs, repository.rs have zero imports from axum, sqlx, or any web/ORM framework. Infrastructure implements the traits.
6. Aggregates collect events. Command methods push events to an internal Vec. The use case handler calls take_events() after saving, then publishes them. The aggregate never knows about the event bus.
7. reconstitute() loads from DB. A pub(crate) associated function that builds an aggregate without validation or event generation. Only infrastructure code calls it.
8. File-per-use-case replaces god services. Each use case is a free async function in its own file with only the dependencies it needs. No 500-line service struct.

Usage Scenarios

Scenario 1: "I'm modeling an order with line items, totals, and status transitions" → Build an Order aggregate with private fields. Status transitions are command methods (place(), cancel()) that return Result and push domain events. Line items are entities owned by the aggregate.

Scenario 2: "I have Money, Currency, Email used across multiple features" → Put these in shared/models.rs as value objects with validated constructors. Each feature imports them but owns its own aggregates and business logic.

Scenario 3: "My service struct has 500 lines and 10 injected dependencies" → Split into file-per-use-case. Move business logic from service methods to aggregate command methods. Each use case handler takes only the 2-3 dependencies it needs.

Scenario 4: "I need to save an aggregate but domain code shouldn't know about sqlx" → Define a repository trait in the feature (repository.rs). Implement it in infrastructure/persistence/ with separate DB row structs. Map DB rows to domain objects via reconstitute().

Scenario 5: "My model.rs has 400 lines with aggregate, entities, and value objects" → Promote to models.rs + models/ folder. Split into models/order.rs, models/order_item.rs, models/value_objects.rs. Imports from outside the feature don't change.

Reference Index

Cross-References