Events Across Boundaries - Event-Driven Integration | OneNoughtOne

0/290

System Design (LLD)Event-Driven Integration

Event-Driven Integration

LevelAdvanced

Duration90 mins

TopicEvent-Driven Integration

1 / 4

Events Across Boundaries

The Challenge of Cross-Boundary Events

In the previous modules, we explored events within a single application—domain events raised by aggregates, handlers processing them, and event buses coordinating delivery. These patterns work beautifully when everything lives in the same process, shares the same memory, and operates under a single deployment boundary.

But real-world systems rarely exist in isolation. Modern software architectures span multiple services, teams, programming languages, and even organizations. The moment events need to leave the cozy confines of a single application and travel to another system, everything becomes more complex.

This page examines the fundamental challenges and patterns for events that cross boundaries—whether those boundaries are between microservices, between bounded contexts, between organizations, or between synchronous and asynchronous worlds.

What You Will Learn

By the end of this page, you will understand: the different types of boundaries events must cross, the fundamental challenges of cross-boundary event communication, architectural patterns for designing events at boundaries, and how to maintain loose coupling while enabling integration across system boundaries.

Understanding System Boundaries

Before we can effectively design events that cross boundaries, we must understand what boundaries actually are and why they exist. A boundary is any demarcation that separates one part of a system from another, creating different contexts, ownership, or execution environments.

Boundaries exist for excellent reasons:

Organizational: Different teams own different services, with distinct release cycles and priorities
Technical: Different programming languages, databases, or infrastructure choices
Domain: Different bounded contexts with their own ubiquitous languages and models
Operational: Different scaling characteristics, availability requirements, or deployment topologies
Security: Different trust levels, compliance requirements, or data classification zones

Types of Boundaries Events Must Cross
Boundary Type	Description	Event Challenges	Example
Process Boundary	Different operating system processes, possibly on same machine	Requires serialization; no shared memory; network or IPC overhead	Sidecar proxy receiving events from main application
Service Boundary	Different microservices with dedicated responsibilities	Network latency; partial failures; independent deployments	Order service publishing OrderPlaced to Inventory service
Bounded Context Boundary	Different domain models with distinct ubiquitous languages	Translation required; anti-corruption layers; context mapping	Sales context's 'Customer' vs Support context's 'User'
Team Boundary	Different organizational units with independent ownership	Coordination overhead; versioning contracts; communication overhead	Platform team events consumed by multiple product teams
Organization Boundary	Different companies or legal entities	Trust issues; contractual obligations; external API stability	Payment gateway publishing transaction events to merchants
Temporal Boundary	Events processed at different times than produced	Ordering challenges; eventual consistency; replay scenarios	Analytics processing yesterday's events today

The Fundamental Boundary Truth

Every boundary you cross adds latency, potential failure modes, and complexity. The goal is not to eliminate boundaries—they provide essential organizational and technical benefits. The goal is to design events that cross boundaries cleanly, with clear contracts and minimal coupling.

In-Process vs Cross-Process Events

The first boundary to understand is the process boundary—the fundamental divide between events that stay within a single running application and events that must traverse the network to reach other systems.

In-process events enjoy significant advantages:

Direct object references (no serialization needed)
Synchronous or in-memory async dispatch
Shared type system and compiler checks
Transactional guarantees can be maintained
No network latency or failure modes

Cross-process events face significant challenges:

Must be serialized to bytes and deserialized back
Network is inherently unreliable (latency, partitions, failures)
No shared type system—receivers must interpret bytes
Transactions cannot span process boundaries
Ordering and exactly-once delivery are hard problems

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
// In-process event: uses direct object references
interface OrderPlacedEvent {
    readonly orderId: string;
    readonly customer: Customer;      // Direct object reference
    readonly items: OrderItem[];      // Complex nested objects
    readonly placedAt: Date;          // Native Date object
    readonly metadata: Map<string, unknown>;  // Complex collection
}
 
// Handler receives the exact same object instance
class InventoryReservationHandler {
    handle(event: OrderPlacedEvent): void {
        // Can directly access nested objects
        const customerId = event.customer.id;
        const customerTier = event.customer.loyaltyTier;
        
        // Can use complex types directly
        for (const item of event.items) {
            this.reserveInventory(item.productId, item.quantity);
        }
        
        // Can access native JavaScript types
        const dayOfWeek = event.placedAt.getDay();
        const hasExpressShipping = event.metadata.get("expressShipping");
    }
}

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
// Cross-process event: must use primitive/serializable types
interface OrderPlacedIntegrationEvent {
    readonly eventId: string;         // Unique identifier for idempotency
    readonly eventType: "OrderPlaced"; // Explicit type discriminator
    readonly version: 1;              // Schema version
    readonly timestamp: string;       // ISO 8601 string, not Date object
    
    // All data must be serializable primitives
    readonly payload: {
        readonly orderId: string;
        readonly customerId: string;      // Just the ID, not full object
        readonly customerTier: string;    // Primitive representation
        readonly items: ReadonlyArray<{
            readonly productId: string;
            readonly quantity: number;
            readonly unitPriceInCents: number;  // Avoid floating point
        }>;
        readonly totalAmountInCents: number;
        readonly currency: string;
    };
    
    // Metadata for tracing and debugging
    readonly metadata: {
        readonly correlationId: string;
        readonly causationId: string;
        readonly source: string;
    };
}
 
// Handler receives deserialized data, must validate
class ExternalInventoryHandler {
    async handle(rawEvent: unknown): Promise<void> {
        // Must validate and parse incoming data
        const event = this.parseAndValidate(rawEvent);
        
        // Work with primitive types
        const customerId = event.payload.customerId;
        
        // Parse timestamps explicitly
        const placedAt = new Date(event.timestamp);
        
        // Convert cents to dollars if needed
        const totalDollars = event.payload.totalAmountInCents / 100;
    }
    
    private parseAndValidate(raw: unknown): OrderPlacedIntegrationEvent {
        // Schema validation, type checking, version handling
        // This is essential for cross-boundary events
    }
}

The Serialization Tax

Cross-process events pay a 'serialization tax'—every piece of data must be convertible to bytes and back. This eliminates object references, complex types, and behaviors. Design integration events with serialization in mind from the start, using primitives, explicit type discriminators, and version information.

Domain Events vs Integration Events

One of the most critical distinctions in event-driven architecture is between Domain Events and Integration Events. While related, they serve fundamentally different purposes and should be designed differently.

Domain Events are internal to a bounded context:

Express facts about domain state changes
Use the ubiquitous language of that context
Can expose rich domain objects and concepts
Tight coupling is acceptable (same codebase)
Can change frequently as the domain model evolves

Integration Events cross bounded context or service boundaries:

Express facts in a way external consumers can understand
Use neutral, widely-understood vocabulary
Expose only serializable, stable data
Loose coupling is essential (different teams/systems)
Must be versioned and evolved carefully

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Domain Event: Rich, internal representation
interface CustomerPromotedToVIP extends DomainEvent {
    readonly aggregateId: CustomerId;
    readonly customer: Customer;          // Full aggregate
    readonly previousTier: LoyaltyTier;   // Domain value object
    readonly newTier: LoyaltyTier;        // Domain value object
    readonly promotionReason: PromotionReason;  // Domain enum
    readonly eligibleBenefits: Benefit[];  // Complex domain objects
}
 
// Uses domain-specific concepts freely
// Consumers are within the same bounded context
// Can expose complex domain objects
// Changes as domain model evolves

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Integration Event: Stable, external representation
interface CustomerTierChangedEvent {
    readonly eventType: "customer.tier.changed";
    readonly version: 1;
    readonly eventId: string;
    readonly timestamp: string;
    readonly payload: {
        readonly customerId: string;
        readonly previousTier: "STANDARD" | "GOLD" | "VIP";
        readonly newTier: "STANDARD" | "GOLD" | "VIP";
        readonly changedAt: string;
    };
}
 
// Uses stable, primitive types
// Consumers may be external systems
// No internal domain concepts exposed
// Versioned for backward compatibility

The Translation Layer:

A well-designed system maintains a clear separation between domain and integration events. Domain events flow freely within a bounded context, triggering internal handlers. When an event needs to cross boundaries, a translation layer (sometimes called an Anti-Corruption Layer or ACL) transforms the domain event into an integration event.

This translation serves several purposes:

Shields internal model from external exposure: Domain concepts stay private
Stabilizes external contracts: Integration events change less frequently
Enables independent evolution: Domain model can change without breaking consumers
Filters sensitive data: Only appropriate data leaves the boundary

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
// Translation service converts domain events to integration events
class CustomerEventTranslator {
    translate(domainEvent: DomainEvent): IntegrationEvent | null {
        if (domainEvent instanceof CustomerPromotedToVIP) {
            return this.translateCustomerPromotion(domainEvent);
        }
        if (domainEvent instanceof CustomerDowngraded) {
            return this.translateCustomerDowngrade(domainEvent);
        }
        // Some domain events don't need to be published externally
        return null;
    }
    
    private translateCustomerPromotion(
        event: CustomerPromotedToVIP
    ): CustomerTierChangedEvent {
        return {
            eventType: "customer.tier.changed",
            version: 1,
            eventId: generateEventId(),
            timestamp: new Date().toISOString(),
            payload: {
                customerId: event.customer.id.value,
                previousTier: this.tierToString(event.previousTier),
                newTier: this.tierToString(event.newTier),
                changedAt: event.occurredAt.toISOString(),
            },
        };
    }
    
    private tierToString(tier: LoyaltyTier): "STANDARD" | "GOLD" | "VIP" {
        // Map internal domain enum to stable external strings
        switch (tier.value) {
            case LoyaltyTierValue.STANDARD: return "STANDARD";
            case LoyaltyTierValue.GOLD: return "GOLD";
            case LoyaltyTierValue.VIP: return "VIP";
            default: throw new Error(`Unknown tier: ${tier}`);
        }
    }
}
 
// Usage in application service or handler
class CustomerEventPublisher {
    constructor(
        private translator: CustomerEventTranslator,
        private integrationEventBus: IntegrationEventBus,
    ) {}
    
    async handleDomainEvent(event: DomainEvent): Promise<void> {
        const integrationEvent = this.translator.translate(event);
        if (integrationEvent) {
            await this.integrationEventBus.publish(integrationEvent);
        }
    }
}

Not All Domain Events Become Integration Events

Many domain events are purely internal and should never leave their bounded context. An 'OrderRecalculated' event might trigger internal discount logic but has no relevance to external systems. The translation layer acts as a filter, publishing only events that external consumers need.

Context Mapping for Event Integration

Domain-Driven Design introduces Context Mapping—a set of patterns for how bounded contexts relate to each other. These patterns directly influence how events flow between contexts and who controls the event contracts.

Understanding context mapping is essential for event-driven integration because it determines:

Who defines the event schema?
Who must adapt when schemas change?
What translation is required at boundaries?
How tightly are the contexts coupled?

Context Mapping Patterns and Event Implications
Pattern	Relationship	Event Flow	Schema Control
Shared Kernel	Contexts share a common subset	Shared event definitions used by both	Both teams collaborate on shared events
Customer-Supplier	Upstream produces, downstream consumes	Events flow downstream; supplier prioritizes customer needs	Upstream defines; downstream adapts
Conformist	Downstream fully conforms to upstream	Downstream uses upstream's events directly	Upstream controls completely; downstream has no input
Anti-Corruption Layer	Downstream protects itself from upstream	Downstream translates upstream events to internal model	Upstream controls; downstream translates
Published Language	Shared, documented integration language	Well-documented, versioned event contracts	Neutral schema; both sides conform
Open Host Service	Upstream exposes stable, public API/events	Upstream publishes stable integration events	Upstream maintains stable public contract

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
// External event from another bounded context (Payments)
interface PaymentProcessedExternalEvent {
    event_type: "PAYMENT_COMPLETED";  // Their naming convention
    payload: {
        transaction_id: string;
        order_reference: string;       // They call it 'order_reference'
        amount_cents: number;
        currency_code: string;
        payment_method: string;
        processed_timestamp: string;
    };
}
 
// Our internal domain event (Orders context)
interface OrderPaymentReceivedEvent extends DomainEvent {
    readonly orderId: OrderId;
    readonly paymentId: PaymentId;
    readonly amount: Money;
    readonly paidAt: Date;
}
 
// Anti-Corruption Layer translates external to internal
class PaymentACL {
    translatePaymentCompleted(
        external: PaymentProcessedExternalEvent
    ): OrderPaymentReceivedEvent {
        // Validate external data
        if (!external.payload.order_reference) {
            throw new InvalidExternalEventError(
                "Missing order_reference in payment event"
            );
        }
        
        // Translate to our domain language
        return {
            eventType: "OrderPaymentReceived",
            occurredAt: new Date(external.payload.processed_timestamp),
            aggregateType: "Order",
            aggregateId: OrderId.from(external.payload.order_reference),
            
            // Map to our domain concepts
            orderId: OrderId.from(external.payload.order_reference),
            paymentId: PaymentId.from(external.payload.transaction_id),
            amount: Money.fromCents(
                external.payload.amount_cents,
                Currency.from(external.payload.currency_code)
            ),
            paidAt: new Date(external.payload.processed_timestamp),
        };
    }
}
 
// Integration event handler uses ACL
class PaymentEventConsumer {
    constructor(
        private acl: PaymentACL,
        private domainEventBus: DomainEventBus,
    ) {}
    
    async onPaymentCompleted(raw: unknown): Promise<void> {
        const externalEvent = this.parseExternalEvent(raw);
        
        // ACL translates to our domain language
        const domainEvent = this.acl.translatePaymentCompleted(externalEvent);
        
        // Now we can process using our domain handlers
        await this.domainEventBus.publish(domainEvent);
    }
}

The Power of Anti-Corruption Layers

ACLs protect your domain model from external pollution. Without an ACL, external naming conventions, data structures, and concepts leak into your codebase. With an ACL, you translate once at the boundary and your domain stays pure. This makes your system resilient to external changes—only the ACL needs updating.

The Eight Fallacies and Event Distribution

When events cross process and network boundaries, we enter the realm of distributed systems. The famous Eight Fallacies of Distributed Computing become directly relevant:

The network is reliable — Networks fail; events may not arrive
Latency is zero — Events take time to propagate
Bandwidth is infinite — Large event payloads have real costs
The network is secure — Events may be intercepted or tampered
Topology doesn't change — Services move; addresses change
There is one administrator — Multiple teams, different priorities
Transport cost is zero — Serialization, network, and parsing have overhead
The network is homogeneous — Different technologies must interoperate

Each fallacy creates specific challenges for cross-boundary events:

Critical Challenges for Cross-Boundary Events

•Delivery Guarantees: Networks fail, so events may be lost. Do you guarantee at-least-once, at-most-once, or exactly-once delivery? Each has profound implications.
•Ordering Guarantees: Events may arrive out of order. If 'OrderCancelled' arrives before 'OrderPlaced', how do you handle it?
•Idempotency: At-least-once delivery means events may arrive multiple times. Handlers must handle duplicates gracefully.
•Eventual Consistency: Events take time to propagate. Systems will be temporarily inconsistent. How long is acceptable?
•Partial Failures: Some consumers may receive an event while others don't. The system is in an inconsistent state.
•Schema Evolution: Producers and consumers evolve independently. Old consumers must handle new events; new consumers must handle old events.
•Observability: When events span multiple services, tracing and debugging becomes significantly harder.

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
// Integration event with delivery safety features
interface RobustIntegrationEvent {
    // Identity for deduplication
    readonly eventId: string;           // UUID, unique per event
    readonly idempotencyKey: string;    // Business key for deduplication
    
    // Ordering information
    readonly sequenceNumber: number;    // Ordering within aggregate
    readonly aggregateVersion: number;  // Aggregate version when raised
    
    // Timing for timeout/delay detection
    readonly timestamp: string;         // When event occurred
    readonly publishedAt: string;       // When event was published
    
    // Tracing for debugging
    readonly correlationId: string;     // Request correlation
    readonly causationId: string;       // Parent event that caused this
    readonly source: string;            // Publishing service
    
    // Standard payload
    readonly eventType: string;
    readonly version: number;
    readonly payload: unknown;
}
 
// Robust event handler with idempotency
class RobustEventHandler {
    constructor(
        private eventStore: ProcessedEventStore,
        private businessLogic: BusinessLogic,
    ) {}
    
    async handle(event: RobustIntegrationEvent): Promise<void> {
        // Step 1: Check for duplicate processing
        const alreadyProcessed = await this.eventStore.wasProcessed(
            event.eventId
        );
        if (alreadyProcessed) {
            console.log(`Event ${event.eventId} already processed, skipping`);
            return;
        }
        
        // Step 2: Check for out-of-order delivery
        const lastSequence = await this.eventStore.getLastSequence(
            event.aggregateId
        );
        if (event.sequenceNumber <= lastSequence) {
            console.warn(`Out-of-order event detected: ${event.eventId}`);
            // Decide: skip, queue for later, or process anyway
        }
        
        // Step 3: Process the event
        await this.businessLogic.process(event);
        
        // Step 4: Record successful processing
        await this.eventStore.markProcessed(event.eventId, event.sequenceNumber);
    }
}

Exactly-Once Is a Lie (Sort Of)

True exactly-once delivery is impossible in distributed systems (proven by the Two Generals Problem). What we implement is effectively-exactly-once: at-least-once delivery combined with idempotent handlers. Events may be delivered multiple times, but processing them multiple times produces the same result.

Event Contracts as APIs

When events cross boundaries, they become contracts—formal agreements between producers and consumers about what data will be provided and in what format. Just like REST or gRPC APIs, integration events require careful contract design.

Key Contract Considerations:

Event Contract Design Principles

•Explicit Type Discriminators: Every event must have a clear type identifier (e.g., 'order.placed', 'customer.registered') that consumers can switch on.
•Version Information: Include schema version so consumers can handle different versions appropriately.
•Self-Describing: Events should contain enough context to be understood without external lookups (within reason).
•Stable Naming: Once published, event type names should never change. Deprecate and introduce new types instead.
•Minimal but Complete: Include all data consumers need, but no more. Avoid including data 'just in case'.
•No Nulls for Required Fields: If a field is sometimes null, make it optional explicitly, don't rely on null values.

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
/**
 * Event Contract: Order Placed
 * 
 * Published when a customer successfully places an order.
 * This is a stable, versioned integration event designed for 
 * cross-boundary consumption.
 * 
 * Consumers: Inventory, Shipping, Notifications, Analytics
 * 
 * @version 1 - Initial version
 * @since 2024-01-15
 */
interface OrderPlacedV1 {
    // === Identity ===
    /** Unique event identifier (UUID v4) */
    readonly eventId: string;
    
    /** Event type discriminator */
    readonly eventType: "order.placed";
    
    /** Schema version for this event type */
    readonly version: 1;
    
    // === Timing ===
    /** ISO 8601 timestamp when order was placed */
    readonly occurredAt: string;
    
    // === Payload ===
    readonly payload: {
        /** Unique order identifier */
        readonly orderId: string;
        
        /** Customer identifier (not full customer object) */
        readonly customerId: string;
        
        /** Order line items */
        readonly items: ReadonlyArray<{
            readonly productId: string;
            readonly sku: string;
            readonly quantity: number;
            readonly unitPriceInCents: number;
        }>;
        
        /** Order totals */
        readonly subtotalInCents: number;
        readonly taxInCents: number;
        readonly shippingInCents: number;
        readonly totalInCents: number;
        readonly currency: "USD" | "EUR" | "GBP";
        
        /** Shipping information */
        readonly shippingAddress: {
            readonly line1: string;
            readonly line2?: string;
            readonly city: string;
            readonly region: string;
            readonly postalCode: string;
            readonly country: string;  // ISO 3166-1 alpha-2
        };
        
        /** Selected shipping method */
        readonly shippingMethod: "STANDARD" | "EXPRESS" | "OVERNIGHT";
    };
    
    // === Metadata ===
    readonly metadata: {
        /** Correlation ID for request tracing */
        readonly correlationId: string;
        
        /** Source system identifier */
        readonly source: "order-service";
        
        /** Environment (for routing/filtering) */
        readonly environment: "production" | "staging" | "development";
    };
}
 
// Type guard for runtime validation
function isOrderPlacedV1(event: unknown): event is OrderPlacedV1 {
    if (typeof event !== "object" || event === null) return false;
    const e = event as Record<string, unknown>;
    return (
        e.eventType === "order.placed" &&
        e.version === 1 &&
        typeof e.eventId === "string" &&
        typeof e.occurredAt === "string" &&
        typeof e.payload === "object"
        // ... additional validation
    );
}

Document Your Events

Integration events deserve the same documentation treatment as REST APIs. Document each event type, its purpose, when it's emitted, what data it contains, and which services consume it. Tools like AsyncAPI provide standardized formats for documenting event-driven APIs.

Summary: Events Across Boundaries

Cross-boundary events are fundamentally different from in-process events. Understanding these differences is essential for building robust, evolvable event-driven systems.

Key Takeaways

•Boundaries exist for good reasons — Organizational, technical, domain, and security concerns create natural divisions. Don't fight them; design for them.
•In-process vs cross-process is a fundamental divide — Cross-process events require serialization, lose object references, and face network challenges.
•Domain events ≠ Integration events — Keep them separate. Domain events are rich and internal; integration events are stable and external.
•Translation layers protect your domain — Anti-corruption layers translate external events to your internal language, preventing domain pollution.
•Context mapping determines responsibilities — Understanding upstream/downstream relationships clarifies who controls event schemas.
•Distributed systems fallacies apply — Networks fail, latency exists, ordering isn't guaranteed. Design defensively with idempotency and robust error handling.
•Events are contracts — Treat integration events like APIs: document them, version them, and evolve them carefully.

What's Next:

Now that we understand the fundamental challenges of cross-boundary events, we need to address a critical technical concern: event serialization. How do we convert rich domain objects into bytes that can travel across networks and be understood by systems written in different languages? The next page explores serialization formats, strategies, and trade-offs.

Page Complete

You now understand the fundamental challenges of events crossing system boundaries. You can distinguish between domain and integration events, apply context mapping patterns, design robust event contracts, and anticipate the challenges of distributed event delivery. Next, we'll dive into the technical details of event serialization.