ddd

Domain-Driven Design Patterns

Reference material for applying DDD tactical patterns in .NET. Business methods return the Result<TValue, TError> / Result<Done, TError> type defined in skills/error-handling/SKILL.md.

When to Use DDD

Aggregate count is a weak signal; the shape of the rules decides. Use DDD when invariants span several entities and must hold on every write, when business rules outgrow CRUD, or when event sourcing is planned. When most operations read or write a single entity with little logic, Vertical Slice Architecture is lower ceremony. See knowledge/decisions/adr-005-multi-architecture.md.

Aggregate Root Base

All changes to an aggregate go through the root — never modify child entities directly from outside.

// Domain/Common/AggregateRoot.cs
public interface IHasDomainEvents
{
    IReadOnlyList<IDomainEvent> DomainEvents { get; }
    void ClearEvents();
}

public abstract class AggregateRoot<TId> : IHasDomainEvents
{
    private readonly List<IDomainEvent> _events = [];
    public TId Id { get; protected set; } = default!;
    public IReadOnlyList<IDomainEvent> DomainEvents => _events.AsReadOnly();
    protected void Raise(IDomainEvent @event) => _events.Add(@event);
    public void ClearEvents() => _events.Clear();
}

The non-generic IHasDomainEvents exists because AggregateRoot<OrderId> is not an AggregateRoot<object> — classes are invariant, so infrastructure that collects events across aggregates (interceptors, dispatchers) needs a non-generic handle.

Aggregate Example

// Domain/Orders/Order.cs
public sealed class Order : AggregateRoot<OrderId>
{
    private readonly List<OrderItem> _items = [];
    public IReadOnlyList<OrderItem> Items => _items.AsReadOnly();
    public CustomerId CustomerId { get; private set; } = null!;
    public OrderStatus Status { get; private set; }
    public Money Total { get; private set; } = null!;

    private Order() { } // required by EF Core

    public static Result<Order, DomainError> Create(
        CustomerId customerId, IReadOnlyList<CreateOrderItemData> items, TimeProvider clock)
    {
        if (items.Count == 0)
            return new ValidationError(nameof(items), "Order must have at least one item.");

        var order = new Order { Id = OrderId.New(), CustomerId = customerId, Status = OrderStatus.Pending };
        order._items.AddRange(items.Select(OrderItem.Create));
        order.Total = order._items.Select(i => i.LineTotal).Aggregate((a, b) => a + b);
        order.Raise(new OrderCreatedEvent(order.Id, customerId, clock.GetUtcNow()));
        return order;
    }

    public Result<Done, DomainError> Cancel(TimeProvider clock)
    {
        if (Status == OrderStatus.Shipped)
            return new ConflictError("Order", "cannot cancel a shipped order");

        Status = OrderStatus.Cancelled;
        Raise(new OrderCancelledEvent(Id, clock.GetUtcNow()));
        return Done.Value;
    }
}