System Design (LLD)Event-Driven Design

Introduction to Event-Driven Design

LevelIntermediate

Duration60 mins

TopicEvent-Driven Design

4 / 4

When to Use Events

Making the Right Choice

Understanding event-driven design is not enough—you must know when to apply it. Over-using events creates unnecessary indirection and complexity. Under-using them leaves coupling and extensibility problems unsolved. The goal is principled decision-making: choosing the right communication pattern for each situation.

This page provides practical decision frameworks. You'll learn to recognize situations where events excel, where they're harmful, and the gray areas that require judgment. By the end, you'll be able to confidently choose between events and direct calls for any given scenario.

What You Will Learn

By the end of this page, you will have clear criteria for when to use events, specific scenarios that favor events vs. direct calls, anti-patterns to avoid, and a practical decision flowchart you can apply immediately.

The Core Decision Question

When deciding whether to use events or direct calls, ask yourself one fundamental question:

"Does the caller need to control what happens, or just announce that something happened?"

If the caller must control the response (get a result, ensure specific action, handle failure directly): Use direct calls or commands.
If the caller just needs to announce ("this happened, react if you care"): Use events.

This question cuts through most ambiguity. Let's see how it applies to concrete scenarios.

Applying the Core Question
Scenario	Control Needed?	Recommendation
Process payment for order	Yes—need confirmation and transaction ID	Command/Direct Call
Send order confirmation email	No—email is fire-and-forget	Event
Validate user input	Yes—need validation result immediately	Direct Call
Track analytics event	No—analytics is purely observational	Event
Reserve inventory for order	Maybe—depends on business criticality	See detailed analysis
Notify warehouse of new order	No—warehouse reacts on its own schedule	Event

The 'Need Response' Heuristic

A quick test: if you would check the return value or catch an exception from this call, you probably need control. If you'd ignore the return value anyway, it's a candidate for events.

Scenarios That Favor Events

Let's examine specific scenarios where event-driven design provides clear value.

Scenario 1: Multiple Independent Reactions

•Situation: When something happens, multiple independent components need to react, but they don't affect each other.
•Example: Order placed → send email, update inventory, track analytics, notify warehouse, calculate loyalty points
•Why events: Each reaction is independent. They can succeed or fail independently. Adding new reactions shouldn't require changing the core flow.
•Direct call problem: The caller becomes a god-object coordinating all reactions, tightly coupled to each.

Scenario 2: Cross-Cutting Concerns

•Situation: Operations like logging, auditing, metrics, and caching need to observe business operations without polluting business logic.
•Example: Every state change should be logged, but logging code shouldn't mix with domain logic.
•Why events: Observers subscribe to relevant events and react independently. Business logic stays pure.
•Direct call problem: Every method gains logging/auditing calls, obscuring core logic.

Scenario 3: Future Extensibility Anticipated

•Situation: You expect new reactions to be added over time, and you want to avoid modifying the core component.
•Example: Building a platform that external plugins will extend. Plugins should react to platform events.
•Why events: New handlers can be registered without changing the event publisher. Open for extension, closed for modification.
•Direct call problem: Every new reaction requires modifying the core—risky, requires coordination, accumulates complexity.

Scenario 4: Cross-Module Communication

•Situation: Different modules or bounded contexts need to communicate without creating direct dependencies.
•Example: Order module needs to notify Shipping module, but they shouldn't import each other's code.
•Why events: Events act as contracts between modules. Each module maintains its independence.
•Direct call problem: Creates inter-module dependencies, violating modularity.

Scenario 5: Temporal Decoupling Required

•Situation: The reacting component might be unavailable, slow, or needs to process at its own pace.
•Example: Sending emails—the email service might be slow; orders shouldn't wait for email delivery.
•Why events: Publisher continues immediately; subscriber processes when ready.
•Direct call problem: Caller is blocked by slow subscriber or fails if subscriber is down.

Scenarios That Favor Direct Calls

Not every interaction benefits from event-driven design. Here are scenarios where direct calls are preferable.

Scenario 1: Result Required for Next Step

•Situation: You need the result of an operation to proceed with the current workflow.
•Example: Validating user input before saving. You MUST know if input is valid before proceeding.
•Why direct calls: Events don't return values. You'd have to awkwardly wait for a response event.
•Event problem: Overcomplicates simple request/response patterns with unnecessary indirection.

Scenario 2: Synchronous Transaction Required

•Situation: Operations must complete atomically—all or nothing.
•Example: Transferring money between accounts. Both debit and credit must succeed together.
•Why direct calls: Transaction semantics require synchronous coordination. Events are fire-and-forget.
•Event problem: Eventual consistency doesn't work for atomic operations. Compensation is complex.

Scenario 3: High Cohesion Within Module

•Situation: Operations are tightly related, within the same module, and change together.
•Example: Order class calling its own LineItems to calculate total. These are cohesive.
•Why direct calls: Internal module operations don't benefit from decoupling—they're meant to be coupled.
•Event problem: Adds indirection without benefit. Makes simple operations hard to trace.

Scenario 4: Specific Handler Required

•Situation: There's exactly one component that should handle this, and failure to handle is an error.
•Example: Saving to database. There's one repository, and save must succeed.
•Why direct calls: This is command semantics, not event semantics. You need confirmation.
•Event problem: If no handler exists, you silently fail—dangerous for critical operations.

Scenario 5: Simple, Linear Workflow

•Situation: The flow is simple, well-understood, and unlikely to change.
•Example: Utility function that formats a date. No extensibility needed.
•Why direct calls: Events add complexity. For stable, simple operations, simplicity wins.
•Event problem: Over-engineering. Not every function call needs to be an event.

The Gray Areas: Judgment Required

Some scenarios don't have clear answers. They require judgment based on your specific context, team, and requirements. Let's examine a nuanced example.

Case Study: Inventory Reservation for Orders

When an order is placed, should inventory reservation be:

A command the OrderService calls directly?
A handler that reacts to OrderPlaced event?

The answer depends on your business requirements.

Arguments for Command

•Order shouldn't be confirmed if inventory unavailable
•Customer should see failure immediately
•Order and inventory must be consistent
•It's a critical path operation
•Failure semantics need explicit handling

Arguments for Event

•Inventory service might be slow/unavailable
•Reservation can happen asynchronously
•Business tolerates brief inconsistency
•Other handlers also need OrderPlaced
•Inventory should be independently deployable

gray-area-analysis.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
// ===== OPTION A: Direct Command for Critical-Path Inventory =====
// Use when: inventory availability must be confirmed before order confirmation
 
class OrderServiceWithDirectReservation {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        
        // SYNCHRONOUS: Reserve inventory BEFORE confirming order
        // Customer sees failure immediately if out of stock
        try {
            await this.inventoryService.reserve(order.items); // Command
        } catch (error) {
            if (error instanceof OutOfStockError) {
                throw new OrderFailedException(
                    "Some items are out of stock",
                    error.unavailableItems
                );
            }
            throw error;
        }
        
        await this.orderRepository.save(order);
        
        // Non-critical actions via events
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        return order;
    }
}
 
// ===== OPTION B: Event Handler for Resilient Inventory =====
// Use when: system should accept order and handle inventory async
 
class OrderServiceWithEventReservation {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        order.status = "PENDING_INVENTORY"; // Explicit pending state
        
        await this.orderRepository.save(order);
        
        // ALL reactions via events, including inventory
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        // Order is "accepted" but not "confirmed"
        // Customer will be notified async if inventory fails
        return order;
    }
}
 
class InventoryReservationHandler implements EventHandler<OrderPlacedEvent> {
    async handle(event: OrderPlacedEvent): Promise<void> {
        try {
            await this.inventoryService.reserve(event.payload.items);
            
            await this.eventDispatcher.dispatch({
                type: "InventoryReserved",
                payload: { orderId: event.payload.orderId },
            });
            
        } catch (error) {
            // Async failure—notify customer, potentially cancel order
            await this.eventDispatcher.dispatch({
                type: "InventoryReservationFailed",
                payload: {
                    orderId: event.payload.orderId,
                    reason: error.message,
                },
            });
        }
    }
}
 
// ===== OPTION C: Hybrid—Check then Reserve =====
// Use when: want immediate feedback but eventual reservation
 
class OrderServiceHybrid {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        
        // SYNCHRONOUS check (fast, read-only)
        const available = await this.inventoryService.checkAvailability(order.items);
        if (!available.allAvailable) {
            throw new OrderFailedException("Items unavailable");
        }
        
        await this.orderRepository.save(order);
        
        // Actual reservation via event (more robust)
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        // Note: Small race condition possible—another order might
        // reserve between check and actual reservation
        return order;
    }
}

Context Matters

There's no universally "right" answer. A B2C e-commerce site might prefer sync (immediate customer feedback). A B2B bulk ordering system might prefer async (orders are large, processed in batches). A high-volume flash sale might use the hybrid (prevent overselling but stay resilient). Know your requirements.

Decision Flowchart: Events or Direct Calls?

Here's a practical flowchart to guide your decisions. Start at the top and follow the questions.

┌─────────────────────────────────────────────────────────────────────────────┐
│                     EVENT vs. DIRECT CALL DECISION TREE                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Q1: Do you need a RETURN VALUE to proceed?                                 │
│      │                                                                      │
│      ├── YES ────────────> Use DIRECT CALL (or Command)                     │
│      │                                                                      │
│      └── NO                                                                 │
│          │                                                                  │
│          V                                                                  │
│  Q2: Must the action complete ATOMICALLY with current operation?            │
│      │                                                                      │
│      ├── YES ────────────> Use DIRECT CALL (same transaction)               │
│      │                                                                      │
│      └── NO                                                                 │
│          │                                                                  │
│          V                                                                  │
│  Q3: Might MULTIPLE INDEPENDENT parties need to react?                      │
│      │                                                                      │
│      ├── YES ────────────> Use EVENT (broadcast to many)                    │
│      │                                                                      │
│      └── NO (exactly one)                                                   │
│          │                                                                  │
│          V                                                                  │
│  Q4: Is the caller the AUTHORITY telling receiver what to do?               │
│      │                                                                      │
│      ├── YES ────────────> Use COMMAND (direct or via bus)                  │
│      │                                                                      │
│      └── NO (just announcing)                                               │
│          │                                                                  │
│          V                                                                  │
│  Q5: Will you want to ADD MORE REACTIONS later?                             │
│      │                                                                      │
│      ├── LIKELY ─────────> Use EVENT (extensibility)                        │
│      │                                                                      │
│      └── UNLIKELY                                                           │
│          │                                                                  │
│          V                                                                  │
│  Q6: Are caller and callee in DIFFERENT MODULES/BOUNDED CONTEXTS?           │
│      │                                                                      │
│      ├── YES ────────────> Use EVENT (loose coupling)                       │
│      │                                                                      │
│      └── NO (same module)                                                   │
│          │                                                                  │
│          V                                                                  │
│  DEFAULT: Use DIRECT CALL (simplicity wins)                                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

When in Doubt, Start Simple

If you're unsure, start with direct calls. You can always refactor to events later if coupling becomes a problem. It's easier to add indirection when you need it than to remove premature abstraction. Don't optimize for extensibility you might never need.

Anti-Patterns to Avoid

Understanding when NOT to use events is as important as knowing when to use them. Here are common anti-patterns.

Anti-Pattern 1: Event Soup

•Pattern: Using events for EVERYTHING, even simple internal operations
•Symptom: Code is hard to follow. "Where does this get handled?". Debugging requires searching for subscribers everywhere.
•Problem: Over-abstraction. You've traded direct coupling for hunting through event handlers.
•Fix: Use events for cross-module communication and extensibility points. Use direct calls for within-module cohesive operations.

Anti-Pattern 2: Synchronous Event Waiting

•Pattern: Publishing an event, then immediately waiting for a specific response event
•Symptom: Code like await eventBus.publish(event); const response = await waitForEvent('ResponseEvent')
•Problem: You've recreated request/response with extra complexity. Events aren't designed for this.
•Fix: If you need a response, use a command or direct call. Don't simulate request/response with events.

Anti-Pattern 3: Critical Path Events

•Pattern: Using events for operations that MUST succeed for the workflow to proceed
•Symptom: System appears to succeed, but later handlers fail silently, leaving data inconsistent
•Problem: Events are fire-and-forget. Critical operations need confirmation.
•Fix: Use commands for critical path. Use events for non-critical reactions (notifications, analytics).

Anti-Pattern 4: Event-Based Queries

•Pattern: Publishing an event to "ask" for data: RequestUserProfile → handler returns UserProfileProvided
•Symptom: Simple queries become convoluted multi-step async flows
•Problem: Events are for announcing facts, not for request/response queries. This abuses the pattern.
•Fix: Use direct method calls for queries. Use CQRS if you need read/write separation, but queries are still synchronous.

Anti-Pattern 5: Ordering Dependency Hell

•Pattern: Handlers that must execute in a specific order, with later handlers depending on earlier handlers' side effects
•Symptom: InventoryHandler must run before ShippingHandler which must run before NotificationHandler
•Problem: Events are fundamentally unordered. Imposing order fights the pattern.
•Fix: If order matters, use a saga or orchestrator. Or collapse dependent steps into a single handler.

anti-pattern-examples.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
// ===== ANTI-PATTERN: Synchronous Event Waiting =====
// DON'T DO THIS
 
class BadOrderService {
    async placeOrder(order: Order): Promise<Order> {
        await this.eventBus.publish({ type: "ValidateOrder", payload: order });
        
        // WRONG: Waiting for response event defeats the purpose of events
        const validationResult = await this.waitForEvent("OrderValidated", 5000);
        
        if (!validationResult.isValid) {
            throw new ValidationError(validationResult.errors);
        }
        
        await this.orderRepository.save(order);
        return order;
    }
    
    private async waitForEvent(type: string, timeout: number): Promise<any> {
        // This is an anti-pattern factory
        // You've recreated request/response with extra complexity
    }
}
 
// ===== CORRECT: Use direct call for validation =====
 
class GoodOrderService {
    async placeOrder(order: Order): Promise<Order> {
        // CORRECT: Validation needs a response—use direct call
        const validationResult = await this.validator.validate(order);
        
        if (!validationResult.isValid) {
            throw new ValidationError(validationResult.errors);
        }
        
        await this.orderRepository.save(order);
        
        // CORRECT: Notifications are fire-and-forget—use events
        await this.eventBus.publish({ type: "OrderPlaced", payload: order });
        
        return order;
    }
}
 
// ===== ANTI-PATTERN: Event-Based Query =====
// DON'T DO THIS
 
async function getUserProfile(userId: string): Promise<UserProfile> {
    // WRONG: This is a query, not an event
    await this.eventBus.publish({ type: "RequestUserProfile", payload: { userId } });
    
    const response = await this.waitForEvent("UserProfileProvided", 5000);
    return response.profile;
}
 
// ===== CORRECT: Direct call for queries =====
 
async function getUserProfile(userId: string): Promise<UserProfile> {
    // CORRECT: Queries are synchronous—call the service directly
    return await this.userService.getProfile(userId);
}

Practical Guidelines for Your Codebase

Here are actionable guidelines you can apply in your codebase today.

Guideline 1: Identify Natural Event Points

•Look for places where you write "// TODO: also update X" or "// remember to notify Y"
•These are hints that multiple parties care about something happening
•Consider whether an event would make this cleaner and more extensible

Guideline 2: Start with Domain Events

•The best events correspond to domain language: "Order Placed", "Payment Received", "Shipment Delivered"
•If you're inventing technical events ("DatabaseUpdated"), you might be over-engineering
•Talk to domain experts—what "happenings" do they care about?

Guideline 3: Limit Event Scope Initially

•Start with in-process, synchronous events—simplest possible implementation
•Don't add message brokers until you have a proven need
•You can always migrate to async later; start simple and evolve

Guideline 4: Document Event Contracts

•Treat event schemas as APIs—document them, version them, deprecate gracefully
•Handlers depend on event structure; breaking changes break handlers
•Consider a schema registry or shared types package for larger systems

Guideline 5: Make Handler Discovery Easy

•Use consistent naming: OrderPlacedHandler, OnOrderPlaced, handleOrderPlaced
•Centralize subscription registration so handlers are discoverable
•Consider code comments linking events to handlers for IDE navigation

Refactoring Toward Events

If you have a god-class that coordinates too much, refactor gradually: extract one handler at a time. Keep the direct call initially, add an event alongside, verify the handler works, then remove the direct call. Incremental migration is safer than big-bang rewrites.

Real-World Decision Matrix

Here's a practical decision matrix for common scenarios you'll encounter. Use this as a quick reference.

When to Use Events: Quick Reference
Scenario	Event?	Rationale
Validate user input before processing	No	Need immediate result; direct call
Send confirmation email after order	Yes	Fire-and-forget; order doesn't wait for email
Reserve inventory for order (strict)	No	Critical path; customer needs failure feedback
Reserve inventory for order (tolerant)	Yes	Business accepts async; customer notified later
Log audit entry for compliance	Yes	Cross-cutting; shouldn't pollute business logic
Track analytics for order	Yes	Optional; analytics failure shouldn't affect order
Calculate order total	No	Need result; cohesive with order logic
Notify warehouse of new order	Yes	Different bounded context; temporal decoupling
Save entity to database	No	Need confirmation of save; single handler
Notify multiple third-party integrations	Yes	Multiple independent parties; extensible
Process payment	Depends	Critical: command. Async-tolerant: event + saga
Update recommendation engine with purchase	Yes	Non-critical; ML can process async
Generate invoice PDF	Yes	Async OK; PDF service can be separate
Enrich customer profile with data	Yes	Background processing; not on critical path

Module Summary: Introduction to Event-Driven Design

We've completed the introduction to event-driven design. Let's consolidate everything we've learned across this module.

Module Recap

•What is Event-Driven Design: Events are immutable records of facts. Publishers announce; subscribers react. The publisher doesn't know or care about subscribers.
•Events vs Commands: Events say "this happened" (past tense, broadcast, no response). Commands say "do this" (imperative, targeted, response expected).
•Benefits: Loose coupling, extensibility, resilience, testability, separation of concerns, parallel development, auditing.
•When to Use Events: Multiple reactions, cross-cutting concerns, future extensibility, cross-module communication, temporal decoupling.
•When NOT to Use Events: Need return value, atomic transactions, within-module cohesion, specific handler required, simple linear workflows.

Key Decision Criteria:

Do you need a return value? → Direct call
Must complete atomically? → Direct call
Multiple parties react? → Event
Extensibility expected? → Event
Different modules? → Event
Neither? → Default to direct call (simplicity)

Anti-patterns to avoid:

Event soup (events for everything)
Synchronous event waiting
Critical path events
Event-based queries
Ordering dependency hell

What's next:

In the next module, we'll dive deep into Domain Events—how to identify, design, and implement events that represent meaningful business occurrences. We'll explore event naming conventions, payload design, and the relationship between domain events and domain-driven design.

Module Complete

Congratulations! You now have a solid foundation in event-driven design. You understand what events are, how they differ from commands, their benefits and trade-offs, and most importantly—when to use them. You're ready to learn how to design events that represent your domain effectively.

4 / 4

Loading learning content...

System Design (LLD)Event-Driven Design

Introduction to Event-Driven Design

LevelIntermediate

Duration60 mins

TopicEvent-Driven Design

4 / 4

When to Use Events

Making the Right Choice

What You Will Learn

The Core Decision Question

When deciding whether to use events or direct calls, ask yourself one fundamental question:

"Does the caller need to control what happens, or just announce that something happened?"

If the caller must control the response (get a result, ensure specific action, handle failure directly): Use direct calls or commands.
If the caller just needs to announce ("this happened, react if you care"): Use events.

This question cuts through most ambiguity. Let's see how it applies to concrete scenarios.

Applying the Core Question
Scenario	Control Needed?	Recommendation
Process payment for order	Yes—need confirmation and transaction ID	Command/Direct Call
Send order confirmation email	No—email is fire-and-forget	Event
Validate user input	Yes—need validation result immediately	Direct Call
Track analytics event	No—analytics is purely observational	Event
Reserve inventory for order	Maybe—depends on business criticality	See detailed analysis
Notify warehouse of new order	No—warehouse reacts on its own schedule	Event

The 'Need Response' Heuristic

A quick test: if you would check the return value or catch an exception from this call, you probably need control. If you'd ignore the return value anyway, it's a candidate for events.

Scenarios That Favor Events

Let's examine specific scenarios where event-driven design provides clear value.

Scenario 1: Multiple Independent Reactions

•Situation: When something happens, multiple independent components need to react, but they don't affect each other.
•Example: Order placed → send email, update inventory, track analytics, notify warehouse, calculate loyalty points
•Why events: Each reaction is independent. They can succeed or fail independently. Adding new reactions shouldn't require changing the core flow.
•Direct call problem: The caller becomes a god-object coordinating all reactions, tightly coupled to each.

Scenario 2: Cross-Cutting Concerns

•Situation: Operations like logging, auditing, metrics, and caching need to observe business operations without polluting business logic.
•Example: Every state change should be logged, but logging code shouldn't mix with domain logic.
•Why events: Observers subscribe to relevant events and react independently. Business logic stays pure.
•Direct call problem: Every method gains logging/auditing calls, obscuring core logic.

Scenario 3: Future Extensibility Anticipated

•Situation: You expect new reactions to be added over time, and you want to avoid modifying the core component.
•Example: Building a platform that external plugins will extend. Plugins should react to platform events.
•Why events: New handlers can be registered without changing the event publisher. Open for extension, closed for modification.
•Direct call problem: Every new reaction requires modifying the core—risky, requires coordination, accumulates complexity.

Scenario 4: Cross-Module Communication

•Situation: Different modules or bounded contexts need to communicate without creating direct dependencies.
•Example: Order module needs to notify Shipping module, but they shouldn't import each other's code.
•Why events: Events act as contracts between modules. Each module maintains its independence.
•Direct call problem: Creates inter-module dependencies, violating modularity.

Scenario 5: Temporal Decoupling Required

•Situation: The reacting component might be unavailable, slow, or needs to process at its own pace.
•Example: Sending emails—the email service might be slow; orders shouldn't wait for email delivery.
•Why events: Publisher continues immediately; subscriber processes when ready.
•Direct call problem: Caller is blocked by slow subscriber or fails if subscriber is down.

Scenarios That Favor Direct Calls

Not every interaction benefits from event-driven design. Here are scenarios where direct calls are preferable.

Scenario 1: Result Required for Next Step

•Situation: You need the result of an operation to proceed with the current workflow.
•Example: Validating user input before saving. You MUST know if input is valid before proceeding.
•Why direct calls: Events don't return values. You'd have to awkwardly wait for a response event.
•Event problem: Overcomplicates simple request/response patterns with unnecessary indirection.

Scenario 2: Synchronous Transaction Required

•Situation: Operations must complete atomically—all or nothing.
•Example: Transferring money between accounts. Both debit and credit must succeed together.
•Why direct calls: Transaction semantics require synchronous coordination. Events are fire-and-forget.
•Event problem: Eventual consistency doesn't work for atomic operations. Compensation is complex.

Scenario 3: High Cohesion Within Module

•Situation: Operations are tightly related, within the same module, and change together.
•Example: Order class calling its own LineItems to calculate total. These are cohesive.
•Why direct calls: Internal module operations don't benefit from decoupling—they're meant to be coupled.
•Event problem: Adds indirection without benefit. Makes simple operations hard to trace.

Scenario 4: Specific Handler Required

•Situation: There's exactly one component that should handle this, and failure to handle is an error.
•Example: Saving to database. There's one repository, and save must succeed.
•Why direct calls: This is command semantics, not event semantics. You need confirmation.
•Event problem: If no handler exists, you silently fail—dangerous for critical operations.

Scenario 5: Simple, Linear Workflow

•Situation: The flow is simple, well-understood, and unlikely to change.
•Example: Utility function that formats a date. No extensibility needed.
•Why direct calls: Events add complexity. For stable, simple operations, simplicity wins.
•Event problem: Over-engineering. Not every function call needs to be an event.

The Gray Areas: Judgment Required

Some scenarios don't have clear answers. They require judgment based on your specific context, team, and requirements. Let's examine a nuanced example.

Case Study: Inventory Reservation for Orders

When an order is placed, should inventory reservation be:

A command the OrderService calls directly?
A handler that reacts to OrderPlaced event?

The answer depends on your business requirements.

Arguments for Command

•Order shouldn't be confirmed if inventory unavailable
•Customer should see failure immediately
•Order and inventory must be consistent
•It's a critical path operation
•Failure semantics need explicit handling

Arguments for Event

•Inventory service might be slow/unavailable
•Reservation can happen asynchronously
•Business tolerates brief inconsistency
•Other handlers also need OrderPlaced
•Inventory should be independently deployable

gray-area-analysis.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
// ===== OPTION A: Direct Command for Critical-Path Inventory =====
// Use when: inventory availability must be confirmed before order confirmation
 
class OrderServiceWithDirectReservation {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        
        // SYNCHRONOUS: Reserve inventory BEFORE confirming order
        // Customer sees failure immediately if out of stock
        try {
            await this.inventoryService.reserve(order.items); // Command
        } catch (error) {
            if (error instanceof OutOfStockError) {
                throw new OrderFailedException(
                    "Some items are out of stock",
                    error.unavailableItems
                );
            }
            throw error;
        }
        
        await this.orderRepository.save(order);
        
        // Non-critical actions via events
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        return order;
    }
}
 
// ===== OPTION B: Event Handler for Resilient Inventory =====
// Use when: system should accept order and handle inventory async
 
class OrderServiceWithEventReservation {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        order.status = "PENDING_INVENTORY"; // Explicit pending state
        
        await this.orderRepository.save(order);
        
        // ALL reactions via events, including inventory
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        // Order is "accepted" but not "confirmed"
        // Customer will be notified async if inventory fails
        return order;
    }
}
 
class InventoryReservationHandler implements EventHandler<OrderPlacedEvent> {
    async handle(event: OrderPlacedEvent): Promise<void> {
        try {
            await this.inventoryService.reserve(event.payload.items);
            
            await this.eventDispatcher.dispatch({
                type: "InventoryReserved",
                payload: { orderId: event.payload.orderId },
            });
            
        } catch (error) {
            // Async failure—notify customer, potentially cancel order
            await this.eventDispatcher.dispatch({
                type: "InventoryReservationFailed",
                payload: {
                    orderId: event.payload.orderId,
                    reason: error.message,
                },
            });
        }
    }
}
 
// ===== OPTION C: Hybrid—Check then Reserve =====
// Use when: want immediate feedback but eventual reservation
 
class OrderServiceHybrid {
    async placeOrder(orderData: OrderData): Promise<Order> {
        const order = new Order(orderData);
        
        // SYNCHRONOUS check (fast, read-only)
        const available = await this.inventoryService.checkAvailability(order.items);
        if (!available.allAvailable) {
            throw new OrderFailedException("Items unavailable");
        }
        
        await this.orderRepository.save(order);
        
        // Actual reservation via event (more robust)
        await this.eventDispatcher.dispatch({
            type: "OrderPlaced",
            payload: order.toEventPayload(),
        });
        
        // Note: Small race condition possible—another order might
        // reserve between check and actual reservation
        return order;
    }
}

Context Matters

Decision Flowchart: Events or Direct Calls?

Here's a practical flowchart to guide your decisions. Start at the top and follow the questions.

┌─────────────────────────────────────────────────────────────────────────────┐
│                     EVENT vs. DIRECT CALL DECISION TREE                     │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Q1: Do you need a RETURN VALUE to proceed?                                 │
│      │                                                                      │
│      ├── YES ────────────> Use DIRECT CALL (or Command)                     │
│      │                                                                      │
│      └── NO                                                                 │
│          │                                                                  │
│          V                                                                  │
│  Q2: Must the action complete ATOMICALLY with current operation?            │
│      │                                                                      │
│      ├── YES ────────────> Use DIRECT CALL (same transaction)               │
│      │                                                                      │
│      └── NO                                                                 │
│          │                                                                  │
│          V                                                                  │
│  Q3: Might MULTIPLE INDEPENDENT parties need to react?                      │
│      │                                                                      │
│      ├── YES ────────────> Use EVENT (broadcast to many)                    │
│      │                                                                      │
│      └── NO (exactly one)                                                   │
│          │                                                                  │
│          V                                                                  │
│  Q4: Is the caller the AUTHORITY telling receiver what to do?               │
│      │                                                                      │
│      ├── YES ────────────> Use COMMAND (direct or via bus)                  │
│      │                                                                      │
│      └── NO (just announcing)                                               │
│          │                                                                  │
│          V                                                                  │
│  Q5: Will you want to ADD MORE REACTIONS later?                             │
│      │                                                                      │
│      ├── LIKELY ─────────> Use EVENT (extensibility)                        │
│      │                                                                      │
│      └── UNLIKELY                                                           │
│          │                                                                  │
│          V                                                                  │
│  Q6: Are caller and callee in DIFFERENT MODULES/BOUNDED CONTEXTS?           │
│      │                                                                      │
│      ├── YES ────────────> Use EVENT (loose coupling)                       │
│      │                                                                      │
│      └── NO (same module)                                                   │
│          │                                                                  │
│          V                                                                  │
│  DEFAULT: Use DIRECT CALL (simplicity wins)                                 │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

When in Doubt, Start Simple

Anti-Patterns to Avoid

Understanding when NOT to use events is as important as knowing when to use them. Here are common anti-patterns.

Anti-Pattern 1: Event Soup

•Pattern: Using events for EVERYTHING, even simple internal operations
•Symptom: Code is hard to follow. "Where does this get handled?". Debugging requires searching for subscribers everywhere.
•Problem: Over-abstraction. You've traded direct coupling for hunting through event handlers.
•Fix: Use events for cross-module communication and extensibility points. Use direct calls for within-module cohesive operations.

Anti-Pattern 2: Synchronous Event Waiting

•Pattern: Publishing an event, then immediately waiting for a specific response event
•Symptom: Code like await eventBus.publish(event); const response = await waitForEvent('ResponseEvent')
•Problem: You've recreated request/response with extra complexity. Events aren't designed for this.
•Fix: If you need a response, use a command or direct call. Don't simulate request/response with events.

Anti-Pattern 3: Critical Path Events

•Pattern: Using events for operations that MUST succeed for the workflow to proceed
•Symptom: System appears to succeed, but later handlers fail silently, leaving data inconsistent
•Problem: Events are fire-and-forget. Critical operations need confirmation.
•Fix: Use commands for critical path. Use events for non-critical reactions (notifications, analytics).

Anti-Pattern 4: Event-Based Queries

•Pattern: Publishing an event to "ask" for data: RequestUserProfile → handler returns UserProfileProvided
•Symptom: Simple queries become convoluted multi-step async flows
•Problem: Events are for announcing facts, not for request/response queries. This abuses the pattern.
•Fix: Use direct method calls for queries. Use CQRS if you need read/write separation, but queries are still synchronous.

Anti-Pattern 5: Ordering Dependency Hell

•Pattern: Handlers that must execute in a specific order, with later handlers depending on earlier handlers' side effects
•Symptom: InventoryHandler must run before ShippingHandler which must run before NotificationHandler
•Problem: Events are fundamentally unordered. Imposing order fights the pattern.
•Fix: If order matters, use a saga or orchestrator. Or collapse dependent steps into a single handler.

anti-pattern-examples.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
// ===== ANTI-PATTERN: Synchronous Event Waiting =====
// DON'T DO THIS
 
class BadOrderService {
    async placeOrder(order: Order): Promise<Order> {
        await this.eventBus.publish({ type: "ValidateOrder", payload: order });
        
        // WRONG: Waiting for response event defeats the purpose of events
        const validationResult = await this.waitForEvent("OrderValidated", 5000);
        
        if (!validationResult.isValid) {
            throw new ValidationError(validationResult.errors);
        }
        
        await this.orderRepository.save(order);
        return order;
    }
    
    private async waitForEvent(type: string, timeout: number): Promise<any> {
        // This is an anti-pattern factory
        // You've recreated request/response with extra complexity
    }
}
 
// ===== CORRECT: Use direct call for validation =====
 
class GoodOrderService {
    async placeOrder(order: Order): Promise<Order> {
        // CORRECT: Validation needs a response—use direct call
        const validationResult = await this.validator.validate(order);
        
        if (!validationResult.isValid) {
            throw new ValidationError(validationResult.errors);
        }
        
        await this.orderRepository.save(order);
        
        // CORRECT: Notifications are fire-and-forget—use events
        await this.eventBus.publish({ type: "OrderPlaced", payload: order });
        
        return order;
    }
}
 
// ===== ANTI-PATTERN: Event-Based Query =====
// DON'T DO THIS
 
async function getUserProfile(userId: string): Promise<UserProfile> {
    // WRONG: This is a query, not an event
    await this.eventBus.publish({ type: "RequestUserProfile", payload: { userId } });
    
    const response = await this.waitForEvent("UserProfileProvided", 5000);
    return response.profile;
}
 
// ===== CORRECT: Direct call for queries =====
 
async function getUserProfile(userId: string): Promise<UserProfile> {
    // CORRECT: Queries are synchronous—call the service directly
    return await this.userService.getProfile(userId);
}

Practical Guidelines for Your Codebase

Here are actionable guidelines you can apply in your codebase today.

Guideline 1: Identify Natural Event Points

•Look for places where you write "// TODO: also update X" or "// remember to notify Y"
•These are hints that multiple parties care about something happening
•Consider whether an event would make this cleaner and more extensible

Guideline 2: Start with Domain Events

•The best events correspond to domain language: "Order Placed", "Payment Received", "Shipment Delivered"
•If you're inventing technical events ("DatabaseUpdated"), you might be over-engineering
•Talk to domain experts—what "happenings" do they care about?

Guideline 3: Limit Event Scope Initially

•Start with in-process, synchronous events—simplest possible implementation
•Don't add message brokers until you have a proven need
•You can always migrate to async later; start simple and evolve

Guideline 4: Document Event Contracts

•Treat event schemas as APIs—document them, version them, deprecate gracefully
•Handlers depend on event structure; breaking changes break handlers
•Consider a schema registry or shared types package for larger systems

Guideline 5: Make Handler Discovery Easy

•Use consistent naming: OrderPlacedHandler, OnOrderPlaced, handleOrderPlaced
•Centralize subscription registration so handlers are discoverable
•Consider code comments linking events to handlers for IDE navigation

Refactoring Toward Events

Real-World Decision Matrix

Here's a practical decision matrix for common scenarios you'll encounter. Use this as a quick reference.

When to Use Events: Quick Reference
Scenario	Event?	Rationale
Validate user input before processing	No	Need immediate result; direct call
Send confirmation email after order	Yes	Fire-and-forget; order doesn't wait for email
Reserve inventory for order (strict)	No	Critical path; customer needs failure feedback
Reserve inventory for order (tolerant)	Yes	Business accepts async; customer notified later
Log audit entry for compliance	Yes	Cross-cutting; shouldn't pollute business logic
Track analytics for order	Yes	Optional; analytics failure shouldn't affect order
Calculate order total	No	Need result; cohesive with order logic
Notify warehouse of new order	Yes	Different bounded context; temporal decoupling
Save entity to database	No	Need confirmation of save; single handler
Notify multiple third-party integrations	Yes	Multiple independent parties; extensible
Process payment	Depends	Critical: command. Async-tolerant: event + saga
Update recommendation engine with purchase	Yes	Non-critical; ML can process async
Generate invoice PDF	Yes	Async OK; PDF service can be separate
Enrich customer profile with data	Yes	Background processing; not on critical path

Module Summary: Introduction to Event-Driven Design

We've completed the introduction to event-driven design. Let's consolidate everything we've learned across this module.

Module Recap

•What is Event-Driven Design: Events are immutable records of facts. Publishers announce; subscribers react. The publisher doesn't know or care about subscribers.
•Events vs Commands: Events say "this happened" (past tense, broadcast, no response). Commands say "do this" (imperative, targeted, response expected).
•Benefits: Loose coupling, extensibility, resilience, testability, separation of concerns, parallel development, auditing.
•When to Use Events: Multiple reactions, cross-cutting concerns, future extensibility, cross-module communication, temporal decoupling.
•When NOT to Use Events: Need return value, atomic transactions, within-module cohesion, specific handler required, simple linear workflows.

Key Decision Criteria:

Do you need a return value? → Direct call
Must complete atomically? → Direct call
Multiple parties react? → Event
Extensibility expected? → Event
Different modules? → Event
Neither? → Default to direct call (simplicity)

Anti-patterns to avoid:

Event soup (events for everything)
Synchronous event waiting
Critical path events
Event-based queries
Ordering dependency hell

What's next:

Module Complete

4 / 4

Introduction to Event-Driven Design - Page 4 of 4 | OneNoughtOne