SKILL.md
Domain Modeling
Layer 2: Design Choices
Core Question
What is this concept's role in the domain?
Before modeling in code, understand:
- Is it an Entity (identity matters) or Value Object (interchangeable)?
- What invariants must be maintained?
- Where are the aggregate boundaries?
Domain Concept → Rust Pattern
Domain Concept
Rust Pattern
Ownership Implication
Entity
struct + Id
Owned, unique identity
Value Object
struct + Clone/Copy
Shareable, immutable
Aggregate Root
struct owns children
Clear ownership tree
Repository
trait
Abstracts persistence
Domain Event
enum
Captures state changes
Service
impl block / free fn
Stateless operations
Thinking Prompt
Before creating a domain type:
-
What's the concept's identity?
- Needs unique identity → Entity (Id field)
- Interchangeable by value → Value Object (Clone/Copy)
-
What invariants must hold?
- Always valid → private fields + validated constructor
- Transition rules → type state pattern
-
Who owns this data?
- Single owner (parent) → owned field
- Shared reference → Arc/Rc
- Weak reference → Weak
Trace Up ↑
To domain constraints (Layer 3):
"How should I model a Transaction?"
↑ Ask: What domain rules govern transactions?
↑ Check: domain-fintech (audit, precision requirements)
↑ Check: Business stakeholders (what invariants?)Design Question
Trace To
Ask
Entity vs Value Object
domain-*
What makes two instances "the same"?
Aggregate boundaries
domain-*
What must be consistent together?
Validation rules
domain-*
What business rules apply?
Trace Down ↓
To implementation (Layer 1):
"Model as Entity"
↓ m01-ownership: Owned, unique
↓ m05-type-driven: Newtype for Id
"Model as Value Object"
↓ m01-ownership: Clone/Copy OK
↓ m05-type-driven: Validate at construction
"Model as Aggregate"
↓ m01-ownership: Parent owns children
↓ m02-resource: Consider Rc for shared within aggregateQuick Reference
DDD Concept
Rust Pattern
Example
Value Object
Newtype
struct Email(String);
Entity
Struct + ID
struct User { id: UserId, ... }
Aggregate
Module boundary
mod order { ... }
Repository
Trait
trait UserRepo { fn find(...) }
Domain Event
Enum
enum OrderEvent { Created, ... }
Pattern Templates
Value Object
struct Email(String);
impl Email {
pub fn new(s: &str) -> Result<Self, ValidationError> {
validate_email(s)?;
Ok(Self(s.to_string()))
}
}Entity
struct UserId(Uuid);
struct User {
id: UserId,
email: Email,
// ... other fields
}
impl PartialEq for User {
fn eq(&self, other: &Self) -> bool {
self.id == other.id // Identity equality
}
}Aggregate
mod order {
pub struct Order {
id: OrderId,
items: Vec<OrderItem>, // Owned children
// ...
}
impl Order {
pub fn add_item(&mut self, item: OrderItem) {
// Enforce aggregate invariants
}
}
}Common Mistakes
Mistake
Why Wrong
Better
Primitive obsession
No type safety
Newtype wrappers
Public fields with invariants
Invariants violated
Private + accessor
Leaked aggregate internals
Broken encapsulation
Methods on root
String for semantic types
No validation
Validated newtype
Related Skills
When
See
Type-driven implementation
m05-type-driven
Ownership for aggregates
m01-ownership
Domain error handling
m13-domain-error
Specific domain rules
domain-*