Elct9620 AI Coding Skills Domain Modeling

Related Skills

• Need to persist domain objects? → Use schema for database table design
• Deciding how to structure classes around patterns? → Use design-patterns
• Deciding where the domain layer lives and whether DDD is warranted at all? → Use clean-architecture first; it owns the style decision (Pure CA vs CA+DDD)

Relationship to Clean Architecture

DDD is layered on top of Clean Architecture's Entities layer, not an alternative to it. CA decides where business rules live (the innermost layer); DDD decides how they are structured (Entity, Value Object, Aggregate, Domain Event).

This skill assumes the decision to use DDD has already been made. If the system is small, CRUD-heavy, and has no real invariants or aggregates, plain CA without DDD is a better fit — the Entities layer is just entities/ holding simple business objects. Consult clean-architecture for that decision before reaching for this skill.

Applicability Rubric

Apply when: At least one condition passes. If none pass, the domain is likely too thin for DDD — use plain Clean Architecture instead and keep entities simple.

Core Principles

Building Blocks

Pattern Selection Guide

Snapshot vs Reference

When embedding data from another aggregate, decide: do you need the current value or the value at the time of the action?

Snapshots are Value Objects embedded in the aggregate. They never change even if the source changes later. Use snapshots for anything that affects business correctness if it were to change retroactively (prices, addresses, terms).

Polymorphic Value Objects

When multiple Value Objects share a common concept (e.g., different discount types, different address formats), they must all implement the same method signature. The calling code should never need to type-check or use case/switch statements — polymorphism handles dispatch.

When different Value Object variants need different data to operate (e.g., a percentage discount needs the order total, but a BOGO discount needs line items), design the interface to accept a context that contains all relevant data. Each implementation extracts what it needs:

# All discount types implement the same interface
class PercentageDiscount
  def compute(order)
    order.subtotal * (rate / 100.0)
  end
end

class BuyOneGetOneFreeDiscount
  def compute(order)
    # Same interface — extracts line items from the order context
    eligible = order.line_items.select { |li| li.product_id == product_id }
    eligible.sum { |li| (li.quantity / 2) * li.unit_price.amount }
  end
end

# Caller — no case statement, no type checking
class Order
  def apply_discount(discount)
    @discount_amount = discount.compute(self)
  end
end

Implementation Examples

Value Object — immutable, validated at construction, compared by value:

class Money
  attr_reader :amount, :currency

  def initialize(amount, currency)
    raise ArgumentError, "amount must be positive" if amount < 0
    raise ArgumentError, "currency required" if currency.nil?
    @amount = amount.freeze
    @currency = currency.freeze
    freeze
  end

  def ==(other)
    amount == other.amount && currency == other.currency
  end

  def +(other)
    raise "currency mismatch" unless currency == other.currency
    Money.new(amount + other.amount, currency)
  end
end

Entity — has identity, encapsulates business rules:

class LineItem
  attr_reader :id, :product_id, :quantity, :unit_price

  def initialize(id:, product_id:, quantity:, unit_price:)
    raise ArgumentError, "quantity must be positive" if quantity <= 0
    @id = id
    @product_id = product_id
    @quantity = quantity
    @unit_price = unit_price
  end

  def subtotal
    Money.new(unit_price.amount * quantity, unit_price.currency)
  end

  def ==(other)
    id == other.id  # compared by identity, not value
  end
end

Domain Event — immutable record of what happened:

class OrderPlaced
  attr_reader :order_id, :customer_id, :total_amount, :occurred_at

  def initialize(order_id:, customer_id:, total_amount:, occurred_at: Time.now)
    @order_id = order_id
    @customer_id = customer_id
    @total_amount = total_amount
    @occurred_at = occurred_at
    freeze
  end
end

Completion Rubric

Entity Design

Value Object Design

Aggregate Design

Domain Event Design

Aggregate Design Steps

Aggregates are the hardest part to get right. Let them emerge from use case requirements rather than designing them upfront:

1. Start from the use case — What operation does the user need to perform?
2. Discover the invariant — What business rule must hold true for this operation to succeed?
3. Find the minimum boundary — What's the smallest set of objects needed to enforce it?
4. Choose the root — Which entity is the entry point for all modifications?
5. Reference other aggregates by ID only — Never hold direct object references across aggregate boundaries

Aggregate boundaries should be discovered incrementally as use cases reveal which objects must change together. Avoid designing the full aggregate structure before writing the first test.

Aggregate Sizing Heuristic

Rule of thumb: If two objects must change together to maintain a business rule, they belong in the same aggregate. If they can change independently, they belong in separate aggregates linked by ID.

Example: Order Aggregate

Order (Aggregate Root)
├── OrderId (Value Object)
├── LineItem[] (Entity - has identity within Order)
│   ├── ProductId (Value Object - reference by ID, not object)
│   ├── Quantity (Value Object)
│   └── Price (Value Object - captured at order time)
├── Money totalAmount (Value Object)
└── OrderStatus (Value Object)

Invariant: totalAmount == sum(lineItems.map(price * quantity))
Invariant: at least one LineItem required

Why this boundary?

• LineItems must be inside Order because the total invariant depends on them
• Product is outside — referenced by ID — because it can change independently
• Customer is outside — referenced by ID — an Order doesn't need to enforce Customer rules

Bounded Context

Bounded Contexts define where a model applies. The same real-world concept may have different representations in different contexts.

Context Mapping Patterns

Example: Same Concept, Different Models

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Sales Context  │     │  Shipping Context │     │  Billing Context  │
│                  │     │                   │     │                   │
│  Customer:       │     │  Recipient:       │     │  Payer:           │
│   - name         │     │   - name          │     │   - name          │
│   - email        │     │   - address       │     │   - paymentMethod │
│   - preferences  │     │   - phone         │     │   - billingAddress│
└──────────────────┘     └──────────────────┘     └──────────────────┘

"Customer" in Sales cares about preferences, in Shipping it's a "Recipient" with an address, in Billing it's a "Payer" with payment info. Don't force one model to serve all contexts.

Directory Structure

Directory naming depends on how many bounded contexts the project has. Pick once at project start — mixing styles creates confusion.

For the multi-context case, avoid these anti-patterns:

Not doing DDD at all? If the project is pure Clean Architecture with no aggregates or ubiquitous-language tension, the directory should be entities/, not domain/. See clean-architecture for the style decision and naming guide — this section only applies once DDD has been chosen.

Migrating from Monolith to Bounded Contexts

Splitting a monolithic model into bounded contexts is incremental work. Don't try to do it all at once.

1. Identify seams — Find groups of fields that change together and are used by the same team or feature
2. Introduce a facade — Keep the monolithic model but add context-specific interfaces on top of it
3. Extract one context at a time — Move the simplest, most independent context out first
4. Use events for synchronization — Contexts that used to share a database row now communicate via domain events
5. Retire the monolith — Once all contexts are extracted, remove the original model

Step 1: Monolith           Step 2: Facades          Step 3: Extract
┌─────────────┐         ┌──────────────────┐     ┌────────┐ ┌────────┐
│    User      │         │ ProfileFacade    │     │Profile │ │  Auth  │
│ - name       │   →     │ AuthFacade       │  →  │Context │ │Context │
│ - email      │         │ BillingFacade    │     └────────┘ └────────┘
│ - password   │         │   ↓ delegates    │     ┌────────┐
│ - card_info  │         │   User (legacy)  │     │Billing │
│ - prefs      │         └──────────────────┘     │Context │
└─────────────┘                                   └────────┘

Key rule: Each step should be independently deployable and testable. If a step requires a big-bang migration, the boundary is in the wrong place.

Domain Event Patterns

Domain Events capture side effects and enable loose coupling between aggregates and contexts.

When to Raise Events

Event Flow

Order.place()
  → raises OrderPlaced { orderId, customerId, items[], totalAmount, occurredAt }
    → Shipping context: creates Shipment
    → Billing context: initiates payment
    → Notification context: sends confirmation email

Each context handles the event independently — if Shipping fails, it doesn't roll back the Order.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.