Domain-Driven Design Basics for Developers

Domain-Driven Design helps build software that matches business complexity. It's about understanding the domain deeply and reflecting that understanding in code.

Core Concepts#

Strategic Design:
- Bounded Context: Clear boundaries around domain models
- Ubiquitous Language: Shared vocabulary between devs and domain experts
- Context Mapping: Relationships between bounded contexts

Tactical Design:
- Entities: Objects with identity
- Value Objects: Objects defined by attributes
- Aggregates: Consistency boundaries
- Domain Events: Significant occurrences
- Repositories: Data access abstraction

Bounded Contexts#

// Different contexts have different models of the same concept

// Sales Context - Customer
namespace Sales {
  interface Customer {
    id: string;
    name: string;
    email: string;
    creditLimit: number;
    paymentTerms: string;
  }
}

// Shipping Context - Customer
namespace Shipping {
  interface Customer {
    id: string;
    name: string;
    shippingAddresses: Address[];
    preferredCarrier: string;
  }
}

// Support Context - Customer
namespace Support {
  interface Customer {
    id: string;
    name: string;
    email: string;
    supportTier: 'basic' | 'premium' | 'enterprise';
    openTickets: number;
  }
}

// Anti-corruption layer between contexts
class CustomerAdapter {
  constructor(
    private salesCustomer: Sales.Customer,
    private supportService: SupportService
  ) {}

  toSupportCustomer(): Support.Customer {
    return {
      id: this.salesCustomer.id,
      name: this.salesCustomer.name,
      email: this.salesCustomer.email,
      supportTier: this.mapPaymentTermsToTier(this.salesCustomer.paymentTerms),
      openTickets: 0,
    };
  }

  private mapPaymentTermsToTier(terms: string): Support.Customer['supportTier'] {
    if (terms === 'enterprise') return 'enterprise';
    if (terms === 'net-30') return 'premium';
    return 'basic';
  }
}

Entities and Value Objects#

// Entity: Has identity, can change over time
class Order {
  constructor(
    public readonly id: OrderId,
    private customerId: CustomerId,
    private items: OrderItem[],
    private status: OrderStatus
  ) {}

  addItem(item: OrderItem): void {
    if (this.status !== 'draft') {
      throw new Error('Cannot modify non-draft order');
    }
    this.items.push(item);
  }

  submit(): void {
    if (this.items.length === 0) {
      throw new Error('Cannot submit empty order');
    }
    this.status = 'submitted';
  }

  get total(): Money {
    return this.items.reduce(
      (sum, item) => sum.add(item.subtotal),
      Money.zero('USD')
    );
  }
}

// Value Object: Immutable, defined by attributes
class Money {
  private constructor(
    public readonly amount: number,
    public readonly currency: string
  ) {
    if (amount < 0) throw new Error('Amount cannot be negative');
  }

  static of(amount: number, currency: string): Money {
    return new Money(amount, currency);
  }

  static zero(currency: string): Money {
    return new Money(0, currency);
  }

  add(other: Money): Money {
    if (this.currency !== other.currency) {
      throw new Error('Cannot add different currencies');
    }
    return new Money(this.amount + other.amount, this.currency);
  }

  multiply(factor: number): Money {
    return new Money(this.amount * factor, this.currency);
  }

  equals(other: Money): boolean {
    return this.amount === other.amount && this.currency === other.currency;
  }
}

// Another value object
class Address {
  constructor(
    public readonly street: string,
    public readonly city: string,
    public readonly postalCode: string,
    public readonly country: string
  ) {
    this.validate();
  }

  private validate(): void {
    if (!this.street || !this.city || !this.country) {
      throw new Error('Invalid address');
    }
  }

  equals(other: Address): boolean {
    return (
      this.street === other.street &&
      this.city === other.city &&
      this.postalCode === other.postalCode &&
      this.country === other.country
    );
  }

  toString(): string {
    return `${this.street}, ${this.city} ${this.postalCode}, ${this.country}`;
  }
}

Aggregates#

// Aggregate Root: Order controls access to OrderItems
class Order {
  private id: OrderId;
  private items: Map<string, OrderItem> = new Map();
  private status: OrderStatus = 'draft';
  private events: DomainEvent[] = [];

  constructor(id: OrderId, private customerId: CustomerId) {
    this.id = id;
    this.addEvent(new OrderCreated(id, customerId));
  }

  // All modifications go through the aggregate root
  addItem(productId: ProductId, quantity: number, price: Money): void {
    this.ensureDraft();

    const existingItem = this.items.get(productId.value);
    if (existingItem) {
      existingItem.increaseQuantity(quantity);
    } else {
      this.items.set(
        productId.value,
        new OrderItem(productId, quantity, price)
      );
    }

    this.addEvent(new OrderItemAdded(this.id, productId, quantity));
  }

  removeItem(productId: ProductId): void {
    this.ensureDraft();
    this.items.delete(productId.value);
    this.addEvent(new OrderItemRemoved(this.id, productId));
  }

  submit(): void {
    this.ensureDraft();
    if (this.items.size === 0) {
      throw new DomainError('Cannot submit empty order');
    }
    this.status = 'submitted';
    this.addEvent(new OrderSubmitted(this.id, this.total));
  }

  private ensureDraft(): void {
    if (this.status !== 'draft') {
      throw new DomainError('Order is not modifiable');
    }
  }

  private addEvent(event: DomainEvent): void {
    this.events.push(event);
  }

  pullEvents(): DomainEvent[] {
    const events = [...this.events];
    this.events = [];
    return events;
  }

  get total(): Money {
    let total = Money.zero('USD');
    for (const item of this.items.values()) {
      total = total.add(item.subtotal);
    }
    return total;
  }
}

// Part of Order aggregate - not directly accessible
class OrderItem {
  constructor(
    public readonly productId: ProductId,
    private quantity: number,
    private unitPrice: Money
  ) {}

  increaseQuantity(amount: number): void {
    this.quantity += amount;
  }

  get subtotal(): Money {
    return this.unitPrice.multiply(this.quantity);
  }
}

Domain Events#

// Domain events represent something that happened
interface DomainEvent {
  readonly occurredAt: Date;
  readonly aggregateId: string;
}

class OrderSubmitted implements DomainEvent {
  readonly occurredAt = new Date();

  constructor(
    public readonly aggregateId: string,
    public readonly orderId: OrderId,
    public readonly total: Money
  ) {}
}

class PaymentReceived implements DomainEvent {
  readonly occurredAt = new Date();

  constructor(
    public readonly aggregateId: string,
    public readonly orderId: OrderId,
    public readonly amount: Money
  ) {}
}

// Event handler
class OrderSubmittedHandler {
  constructor(
    private inventoryService: InventoryService,
    private notificationService: NotificationService
  ) {}

  async handle(event: OrderSubmitted): Promise<void> {
    // Reserve inventory
    await this.inventoryService.reserve(event.orderId);

    // Send confirmation
    await this.notificationService.sendOrderConfirmation(event.orderId);
  }
}

Repositories#

// Repository abstracts data access
interface OrderRepository {
  findById(id: OrderId): Promise<Order | null>;
  save(order: Order): Promise<void>;
  nextId(): OrderId;
}

class PrismaOrderRepository implements OrderRepository {
  constructor(private prisma: PrismaClient, private eventBus: EventBus) {}

  async findById(id: OrderId): Promise<Order | null> {
    const data = await this.prisma.order.findUnique({
      where: { id: id.value },
      include: { items: true },
    });

    if (!data) return null;

    return this.toDomain(data);
  }

  async save(order: Order): Promise<void> {
    const data = this.toPersistence(order);

    await this.prisma.order.upsert({
      where: { id: data.id },
      create: data,
      update: data,
    });

    // Publish domain events
    const events = order.pullEvents();
    for (const event of events) {
      await this.eventBus.publish(event);
    }
  }

  nextId(): OrderId {
    return new OrderId(crypto.randomUUID());
  }

  private toDomain(data: OrderData): Order {
    // Reconstruct aggregate from persistence data
    return Order.reconstitute(
      new OrderId(data.id),
      new CustomerId(data.customerId),
      data.items.map(this.toOrderItem),
      data.status as OrderStatus
    );
  }

  private toPersistence(order: Order): OrderData {
    // Convert aggregate to persistence format
    return {
      id: order.id.value,
      customerId: order.customerId.value,
      status: order.status,
      items: order.items.map((item) => ({
        productId: item.productId.value,
        quantity: item.quantity,
        unitPrice: item.unitPrice.amount,
      })),
    };
  }
}

Application Services#

// Application service orchestrates domain operations
class OrderService {
  constructor(
    private orderRepository: OrderRepository,
    private customerRepository: CustomerRepository,
    private productCatalog: ProductCatalog
  ) {}

  async createOrder(customerId: string): Promise<string> {
    const customer = await this.customerRepository.findById(new CustomerId(customerId));
    if (!customer) throw new Error('Customer not found');

    const orderId = this.orderRepository.nextId();
    const order = new Order(orderId, customer.id);

    await this.orderRepository.save(order);

    return orderId.value;
  }

  async addItem(orderId: string, productId: string, quantity: number): Promise<void> {
    const order = await this.orderRepository.findById(new OrderId(orderId));
    if (!order) throw new Error('Order not found');

    const product = await this.productCatalog.findById(new ProductId(productId));
    if (!product) throw new Error('Product not found');

    order.addItem(product.id, quantity, product.price);

    await this.orderRepository.save(order);
  }

  async submitOrder(orderId: string): Promise<void> {
    const order = await this.orderRepository.findById(new OrderId(orderId));
    if (!order) throw new Error('Order not found');

    order.submit();

    await this.orderRepository.save(order);
  }
}

Best Practices#

Modeling:
✓ Model the domain, not the database
✓ Use ubiquitous language consistently
✓ Keep aggregates small
✓ Protect invariants in aggregate roots

Implementation:
✓ Make implicit concepts explicit
✓ Use value objects for domain concepts
✓ Raise domain events for side effects
✓ Isolate domain from infrastructure

Organization:
✓ One aggregate per transaction
✓ Reference aggregates by ID
✓ Use domain events for cross-aggregate consistency
✓ Keep bounded contexts independent

DDD helps manage domain complexity by aligning code with business concepts. Start with bounded contexts and ubiquitous language. Use aggregates to enforce invariants and domain events for loose coupling. The investment pays off in maintainability and clarity.