Domain Events - Learning Module

Loading content...

0/246

Recap from DDD Chapter

Domain Events: Where DDD Meets Event-Driven Architecture

Before we dive deep into domain events, we need to establish a critical connection: domain events are not an invention of event-driven architecture—they emerge naturally from Domain-Driven Design (DDD). Understanding this connection is essential because it transforms domain events from mere technical mechanisms into powerful modeling tools that capture the heartbeat of your business domain.

In DDD, we model software around the business domain, using a ubiquitous language shared between developers and domain experts. Domain events are a natural extension of this philosophy—they represent something significant that happened in the domain, expressed in the language of the business.

What You Will Learn

By the end of this page, you will understand how domain events connect to DDD concepts, why they matter for domain modeling, and how they serve as the foundation for event-driven architectures. You'll see how thinking in events changes your approach to system design fundamentally.

The DDD Foundation

Domain-Driven Design, introduced by Eric Evans in his seminal 2003 book, provides a framework for tackling complex software by focusing relentlessly on the core domain. Let's revisit the key DDD concepts that directly inform domain event design:

Ubiquitous Language:

The ubiquitous language is a shared vocabulary between developers and domain experts. Every term in the codebase should map directly to a concept that domain experts recognize and use. Domain events are no exception—they should be named and structured using this shared language.

Bounded Contexts:

A bounded context is a boundary within which a particular domain model applies. Within a bounded context, terms have specific, consistent meanings. Domain events often travel between bounded contexts, serving as the communication mechanism that allows different parts of a system to remain loosely coupled while staying synchronized.

Core DDD Building Blocks

•Entities — Objects with a distinct identity that persists over time. Example: A Customer with a unique ID remains the same customer even as their address changes.
•Value Objects — Objects defined entirely by their attributes, with no distinct identity. Example: An Address is defined by its street, city, and postal code.
•Aggregates — Clusters of related entities and value objects that are treated as a single unit for data changes. Example: An Order aggregate containing OrderLines.
•Domain Services — Operations that don't naturally belong to any entity but represent significant domain behavior.
•Repositories — Abstractions for retrieving and persisting aggregates.
•Domain Events — Records of something significant that happened in the domain, expressed in domain language.

Events as First-Class Citizens

In DDD, domain events are not afterthoughts or logging mechanisms—they are first-class citizens of the domain model. When domain experts say 'When an order is placed...' or 'After payment is received...', they're describing domain events. These phrases signal important business occurrences that the system should explicitly model.

What Are Domain Events?

A domain event is an immutable record of something significant that happened in the business domain. The key word here is happened—domain events are always expressed in the past tense because they describe facts that have already occurred.

Characteristics of Domain Events:

Past Tense Naming: Events are named to reflect that they've already occurred: OrderPlaced, PaymentReceived, CustomerRegistered.
Business Significance: Events capture moments that matter to the business, not technical implementation details. OrderPlaced is meaningful; DatabaseRowInserted is not.
Immutability: Once an event occurs, it cannot be changed. You can react to it, compensate for it, or record new events, but you cannot alter history.
Self-Contained: Events carry all the information necessary to understand what happened, without requiring the receiver to query back for context.

domain-event-examples.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
// Domain events are named in past tense and carry meaningful business data
 
interface DomainEvent {
    readonly eventId: string;
    readonly occurredAt: Date;
    readonly aggregateId: string;
}
 
// Event: Something significant happened to an Order
interface OrderPlaced extends DomainEvent {
    readonly eventType: 'OrderPlaced';
    readonly customerId: string;
    readonly orderItems: ReadonlyArray<{
        readonly productId: string;
        readonly quantity: number;
        readonly unitPrice: number;
    }>;
    readonly totalAmount: number;
    readonly shippingAddress: {
        readonly street: string;
        readonly city: string;
        readonly postalCode: string;
        readonly country: string;
    };
}
 
// Event: Payment was successfully processed
interface PaymentReceived extends DomainEvent {
    readonly eventType: 'PaymentReceived';
    readonly orderId: string;
    readonly paymentMethod: 'credit_card' | 'bank_transfer' | 'wallet';
    readonly amount: number;
    readonly currency: string;
    readonly transactionId: string;
}
 
// Event: An order was shipped to the customer
interface OrderShipped extends DomainEvent {
    readonly eventType: 'OrderShipped';
    readonly orderId: string;
    readonly carrier: string;
    readonly trackingNumber: string;
    readonly estimatedDeliveryDate: Date;
}

Notice how each event tells a complete story. An OrderPlaced event doesn't just say "an order happened"—it captures the customer, the items, the prices, and the shipping destination. Anyone receiving this event has full context without needing to query additional systems.

Domain Events vs Integration Events

A crucial distinction in event-driven systems is between domain events and integration events. While often conflated, they serve different purposes and have different design considerations.

Domain Events:

Live within a single bounded context
Use the internal ubiquitous language of that context
Can contain rich domain objects and references
Are raised by aggregates as part of domain logic
Handlers typically run in the same transaction

Integration Events:

Travel between bounded contexts or external systems
Must use a shared, stable vocabulary
Contain only primitive types and well-known structures
Are published explicitly after domain events are processed
Handlers run in separate transactions, often asynchronously

Domain Events vs Integration Events
Aspect	Domain Events	Integration Events
Scope	Within a bounded context	Across bounded contexts or systems
Naming	Rich domain language	Stable, versioned contracts
Data Types	Domain objects, value objects	Primitives, DTOs, serializable types
Coupling	Tightly coupled to domain model	Loosely coupled, stable over time
Transaction	Same transaction as command	Separate transaction, eventually consistent
Evolution	Can change with domain model	Must be versioned carefully
Examples	`OrderPlaced` (internal)	`OrderPlacedV1` (external API)

event-transformation.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
// Domain event: Rich, internal representation
interface OrderPlacedDomainEvent {
    readonly eventType: 'OrderPlaced';
    readonly eventId: string;
    readonly occurredAt: Date;
    readonly order: Order;  // Full domain aggregate
    readonly customer: Customer;  // Full customer entity
}
 
// Integration event: Stable, serializable, external contract
interface OrderPlacedIntegrationEventV1 {
    readonly eventType: 'OrderPlaced';
    readonly version: 1;
    readonly eventId: string;
    readonly occurredAt: string;  // ISO 8601 string
    readonly orderId: string;
    readonly customerId: string;
    readonly customerEmail: string;  // Denormalized for consumers
    readonly totalAmount: number;
    readonly currency: string;
    readonly itemCount: number;
}
 
// Transformer: Converts domain events to integration events
class OrderEventTransformer {
    toIntegrationEvent(
        domainEvent: OrderPlacedDomainEvent
    ): OrderPlacedIntegrationEventV1 {
        return {
            eventType: 'OrderPlaced',
            version: 1,
            eventId: domainEvent.eventId,
            occurredAt: domainEvent.occurredAt.toISOString(),
            orderId: domainEvent.order.id,
            customerId: domainEvent.customer.id,
            customerEmail: domainEvent.customer.email,
            totalAmount: domainEvent.order.total.amount,
            currency: domainEvent.order.total.currency,
            itemCount: domainEvent.order.items.length,
        };
    }
}

Don't Leak Domain Details

A common mistake is publishing domain events directly to external systems. This creates tight coupling and makes domain evolution painful. Always transform domain events into integration events with stable contracts before publishing externally. Your domain model should be free to evolve without breaking external consumers.

Events in the Aggregate Lifecycle

In DDD, aggregates are the consistency boundaries of your domain. Domain events are raised by aggregates when something significant happens during their lifecycle. This is a crucial pattern: events are not created externally and applied to aggregates—they emerge from aggregate behavior.

The Aggregate-Event Relationship:

A command targets an aggregate (e.g., PlaceOrder)
The aggregate validates the command against its current state and business rules
If valid, the aggregate changes its state and raises domain events
Events are collected and dispatched after the aggregate is persisted
Event handlers react to the events, potentially triggering further commands

aggregate-raising-events.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
// Aggregate that raises domain events during its lifecycle
 
interface DomainEvent {
    readonly eventId: string;
    readonly occurredAt: Date;
}
 
abstract class AggregateRoot {
    private _domainEvents: DomainEvent[] = [];
    
    protected addDomainEvent(event: DomainEvent): void {
        this._domainEvents.push(event);
    }
    
    public pullDomainEvents(): DomainEvent[] {
        const events = [...this._domainEvents];
        this._domainEvents = [];
        return events;
    }
}
 
class Order extends AggregateRoot {
    private _id: string;
    private _customerId: string;
    private _items: OrderItem[] = [];
    private _status: OrderStatus;
    private _totalAmount: number = 0;
    
    private constructor(id: string, customerId: string) {
        super();
        this._id = id;
        this._customerId = customerId;
        this._status = 'draft';
    }
    
    // Factory method that raises creation event
    static create(id: string, customerId: string): Order {
        const order = new Order(id, customerId);
        // Note: We might not raise an event here since it's just a draft
        return order;
    }
    
    // Business method that raises domain event
    place(items: OrderItem[], shippingAddress: ShippingAddress): void {
        // Business rule validation
        if (this._status !== 'draft') {
            throw new Error('Only draft orders can be placed');
        }
        if (items.length === 0) {
            throw new Error('Cannot place an order with no items');
        }
        
        // State change
        this._items = items;
        this._totalAmount = this.calculateTotal(items);
        this._status = 'placed';
        
        // Raise domain event AFTER state change
        this.addDomainEvent({
            eventType: 'OrderPlaced',
            eventId: generateId(),
            occurredAt: new Date(),
            aggregateId: this._id,
            customerId: this._customerId,
            items: items.map(i => ({
                productId: i.productId,
                quantity: i.quantity,
                unitPrice: i.unitPrice
            })),
            totalAmount: this._totalAmount,
            shippingAddress: shippingAddress
        } as OrderPlaced);
    }
    
    // Another business method that raises a different event
    ship(carrier: string, trackingNumber: string): void {
        if (this._status !== 'paid') {
            throw new Error('Only paid orders can be shipped');
        }
        
        this._status = 'shipped';
        
        this.addDomainEvent({
            eventType: 'OrderShipped',
            eventId: generateId(),
            occurredAt: new Date(),
            aggregateId: this._id,
            orderId: this._id,
            carrier,
            trackingNumber,
            estimatedDeliveryDate: this.calculateEstimatedDelivery(carrier)
        } as OrderShipped);
    }
    
    private calculateTotal(items: OrderItem[]): number {
        return items.reduce((sum, item) => sum + item.quantity * item.unitPrice, 0);
    }
    
    private calculateEstimatedDelivery(carrier: string): Date {
        const days = carrier === 'express' ? 2 : 5;
        const date = new Date();
        date.setDate(date.getDate() + days);
        return date;
    }
}

Events Capture Intent, Not Just State

Notice that the events capture why the state changed, not just what changed. An OrderPlaced event is more meaningful than a generic OrderUpdated event. This semantic richness makes events valuable for analytics, auditing, and triggering appropriate downstream reactions.

The Event-First Modeling Mindset

Traditional software modeling often starts with data: "What entities do we need? What attributes do they have?" Event-first modeling inverts this: "What happens in our domain? What events do domain experts talk about?"

This approach, often called Event Storming (developed by Alberto Brandolini), has profound benefits:

Benefits of Event-First Modeling:

Aligns with Business Language: Domain experts naturally think in terms of events. "When a customer registers..." "After an order is placed..." "Once payment is confirmed..."
Reveals Hidden Complexity: The sequence of events often exposes edge cases and business rules that entity modeling misses.
Identifies Bounded Contexts: Events that need to flow between different parts of the business naturally reveal context boundaries.
Enables Parallel Development: Once events are defined, different teams can work on producers and consumers independently.
Improves Traceability: A clear event flow creates an auditable record of business processes.

Data-First Approach

•Start with entity definitions
•Define attributes and relationships
•Add behavior as CRUD operations
•Events (if any) are afterthoughts
•Focus: What data do we store?
•Risk: Missing business processes

Event-First Approach

•Start with domain events
•Define what triggers them
•Derive entities from event data needs
•Commands emerge from event requirements
•Focus: What happens in the business?
•Benefit: Complete process coverage

Example: E-Commerce Order Flow (Event-First)

Instead of starting with Order, Customer, Product entities, we start by asking: What events happen in the order lifecycle?

CustomerRegistered → Customer can now browse and buy
ProductAddedToCart → Customer shows purchase intent
CartCheckedOut → Order creation initiated
OrderPlaced → Order officially submitted
PaymentAuthorized → Payment method validated
PaymentCaptured → Money actually transferred
InventoryReserved → Items set aside for this order
OrderConfirmed → All prerequisites met
OrderPicked → Warehouse picked the items
OrderPacked → Items packaged for shipping
OrderShipped → Handed to carrier
OrderDelivered → Customer received package

From this event flow, the entities, their states, and their relationships become clear. The events reveal the model.

Event Storming Sessions

Event Storming workshops bring together developers and domain experts to collaboratively model domains using sticky notes on a wall. Orange stickies represent events, blue represent commands, yellow represent actors, and pink represent policies. This visual, collaborative approach often uncovers more domain knowledge in a few hours than weeks of traditional requirements gathering.

Events and Eventual Consistency

A fundamental consequence of event-driven design is eventual consistency. When an aggregate raises a domain event and handlers react asynchronously, the system may be temporarily inconsistent—but it will eventually become consistent.

Understanding Eventual Consistency:

In traditional monolithic systems, a single database transaction ensures that all related data is updated atomically. When you place an order, the order is created, inventory is decremented, and the customer's order history is updated—all in one transaction.

In event-driven systems, these operations are decoupled. The Order aggregate raises an OrderPlaced event. An Inventory handler reacts by reserving stock. A Customer Profile handler updates the order history. Each handler may run in its own transaction, possibly on a different database.

The trade-off:

Lost: Immediate, strong consistency across all data
Gained: Scalability, resilience, and loose coupling

eventual-consistency-example.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
// Eventual consistency in action: handlers react to OrderPlaced
 
// Handler 1: Update inventory (eventually)
class InventoryEventHandler {
    async handle(event: OrderPlaced): Promise<void> {
        // This runs in a SEPARATE transaction
        for (const item of event.items) {
            await this.inventoryService.reserveStock(
                item.productId,
                item.quantity,
                event.aggregateId  // orderId for reference
            );
        }
        // If this fails, the order still exists!
        // We need compensation or retry logic
    }
}
 
// Handler 2: Send confirmation email (eventually)
class NotificationEventHandler {
    async handle(event: OrderPlaced): Promise<void> {
        const customer = await this.customerRepository.findById(event.customerId);
        
        await this.emailService.send({
            to: customer.email,
            template: 'order-confirmation',
            data: {
                orderId: event.aggregateId,
                items: event.items,
                total: event.totalAmount
            }
        });
        // Email might arrive before inventory is confirmed!
    }
}
 
// Handler 3: Update analytics (eventually)
class AnalyticsEventHandler {
    async handle(event: OrderPlaced): Promise<void> {
        await this.analyticsService.trackEvent({
            eventType: 'purchase',
            customerId: event.customerId,
            revenue: event.totalAmount,
            products: event.items.map(i => i.productId)
        });
        // Analytics dashboard updates with some delay
    }
}
 
// The order is placed IMMEDIATELY
// Inventory, email, analytics update EVENTUALLY
// The system is consistent OVER TIME

Design for Failure

In eventually consistent systems, handlers can fail independently. What if the inventory handler fails after the order is placed? You need compensation mechanisms (like sagas), retry logic (with idempotency), and monitoring to detect inconsistent states. Eventual consistency is a design philosophy, not a magic solution.

Events and Bounded Context Communication

In DDD, bounded contexts are autonomous areas of the domain, each with its own model and ubiquitous language. Domain events serve as the primary mechanism for communication between bounded contexts, preserving their autonomy while enabling collaboration.

Why Events for Context Communication?

No Shared Model: Each context maintains its own model. Events carry data in a neutral format that each context interprets independently.
Temporal Decoupling: The publishing context doesn't wait for consumers. It fires events and moves on, enabling asynchronous processing.
Selective Consumption: Each context subscribes only to events it cares about, ignoring the rest.
Contract Stability: Integration events form stable contracts that evolve through versioning, not coupling.

Converting Mermaid diagram...

In this architecture:

The Order Context knows nothing about inventory, shipping, or notifications—it just publishes OrderPlaced
The Inventory Context subscribes to OrderPlaced and manages stock in its own terms
The Shipping Context reacts to StockReserved to prepare shipments
The Notification Context sends emails based on various events

Each context can evolve independently. The Order Context could be rewritten in a different language, and as long as it publishes compatible events, consumers are unaffected.

Summary: The DDD-Events Connection

This page has established the critical connection between Domain-Driven Design and domain events. Let's consolidate the key insights:

Key Takeaways

•Domain events emerge from DDD — They are first-class citizens of the domain model, not technical afterthoughts.
•Events capture business significance — Named in past tense, they describe what happened in terms domain experts understand.
•Domain events vs integration events — Internal domain events are rich and coupled to the model; integration events are stable contracts for external communication.
•Aggregates raise events — Events are produced as a result of aggregate behavior, capturing state changes and their intent.
•Event-first modeling reveals better designs — Starting with events uncovers business processes that entity-first modeling often misses.
•Events enable eventual consistency — Decoupled handlers create scalable systems but require careful design for failure scenarios.
•Events connect bounded contexts — They are the communication mechanism that preserves context autonomy while enabling collaboration.

What's Next:

Now that we've established the theoretical foundation connecting DDD and domain events, the next page will dive into the practical aspects of designing domain events—how to identify them, structure their data, and ensure they serve their intended purpose in your architecture.

Page Complete

You now understand how domain events connect to Domain-Driven Design principles. They are not merely a messaging pattern—they are a core modeling concept that captures significant business occurrences and enables loose coupling between system components. Next, we'll learn how to design events effectively.