Domain Events

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

/**
 * INTERNAL DOMAIN EVENT
 * 
 * Rich with internal details, uses internal types.
 * May change freely with refactoring.
 */
class OrderPlaced_Internal implements DomainEvent {
    readonly eventType = 'OrderPlaced';
    constructor(
        readonly eventId: string,
        readonly occurredAt: Date,
        readonly orderId: string,
        readonly customerId: string,
        readonly items: ReadonlyArray<{
            productId: string;
            productName: string;
            sku: string;  // Internal detail
            quantity: number;
            unitPrice: Money;
            warehouseLocation: string;  // Internal routing detail
        }>,
        readonly totalAmount: Money,
        readonly appliedPromotions: AppliedPromotion[],  // Internal detail
        readonly fraudScore: number,  // Very internal
        readonly customerTier: CustomerTier,
        readonly internalNotes: string,  // Never expose
    ) {}
}
 
/**
 * INTEGRATION EVENT
 * 
 * Carefully designed public contract.
 * Stable, minimal, focused on what other contexts need.
 */
namespace Integration {
    export interface OrderPlaced {
        readonly eventType: 'integration.orders.OrderPlaced';
        readonly eventVersion: 1;
        readonly eventId: string;
        readonly occurredAt: string;  // ISO string for cross-language compat
        
        // What other contexts need to know
        readonly orderId: string;
        readonly customerId: string;
        readonly orderTotal: {
            amount: number;
            currency: string;  // String, not enum - easier cross-language
        };
        readonly itemCount: number;  // Summary, not full details
        readonly estimatedShipDate: string;
        
        // Exclude internal details like:
        // - fraudScore (security)
        // - internalNotes (not relevant)
        // - warehouseLocation (internal routing)
        // - appliedPromotions (internal discounting logic)
    }
}
 
/**
 * Mapper that translates internal to integration event.
 * 
 * This is where you control what gets exposed.
 */
class OrderPlacedIntegrationMapper {
    translate(
        internal: OrderPlaced_Internal
    ): Integration.OrderPlaced {
        return {
            eventType: 'integration.orders.OrderPlaced',
            eventVersion: 1,
            eventId: internal.eventId,
            occurredAt: internal.occurredAt.toISOString(),
            
            orderId: internal.orderId,
            customerId: internal.customerId,
            orderTotal: {
                amount: internal.totalAmount.amount,
                currency: internal.totalAmount.currency.toString(),
            },
            itemCount: internal.items.length,
            estimatedShipDate: this.calculateEstimatedShipDate(internal),
        };
    }
    
    private calculateEstimatedShipDate(order: OrderPlaced_Internal): string {
        // Internal logic, exposed as simple date
        const baseDate = new Date();
        baseDate.setDate(baseDate.getDate() + 3);
        return baseDate.toISOString().split('T')[0];
    }
}

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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

/**
 * Well-designed Integration Event Schema
 * 
 * Used as a TypeScript interface and serialized to JSON for wire.
 */
namespace IntegrationEvents {
    /**
     * Base structure for all integration events.
     * Provides consistent metadata across contexts.
     */
    interface IntegrationEventBase {
        /** Fully qualified event type with namespace */
        readonly eventType: string;
        
        /** Schema version for evolution */
        readonly eventVersion: number;
        
        /** Unique identifier for deduplication */
        readonly eventId: string;
        
        /** When the event occurred (ISO-8601) */
        readonly occurredAt: string;
        
        /** Correlation ID for distributed tracing */
        readonly correlationId?: string;
    }
    
    /**
     * OrderPlaced Integration Event (v1)
     * 
     * Published by: Orders context
     * Consumed by: Shipping, Analytics, Loyalty, Fraud
     */
    export interface OrderPlaced_V1 extends IntegrationEventBase {
        eventType: 'orders.OrderPlaced';
        eventVersion: 1;
        
        // Core identifiers
        orderId: string;
        customerId: string;
        
        // Summary information (not full details)
        orderSummary: {
            totalAmount: number;
            currency: string;
            itemCount: number;
            productCategories: string[];  // For routing/analytics
        };
        
        // Shipping-relevant data
        shipping: {
            address: {
                country: string;
                postalCode: string;
                city: string;
                // Full address might be in separate secure channel
            };
            requestedDeliveryDate?: string;
        };
        
        // Customer context (non-sensitive)
        customer: {
            email: string;  // For notifications
            tier: string;   // Gold, Silver, Bronze
            isFirstOrder: boolean;
        };
    }
    
    /**
     * PaymentReceived Integration Event
     * 
     * Published by: Payments context
     * Consumed by: Orders, Billing, Finance
     */
    export interface PaymentReceived_V1 extends IntegrationEventBase {
        eventType: 'payments.PaymentReceived';
        eventVersion: 1;
        
        paymentId: string;
        orderId: string;  // Links back to order
        
        payment: {
            amount: number;
            currency: string;
            method: string;  // 'CARD' | 'BANK' | 'WALLET'
            processedAt: string;
        };
        
        // Don't expose: card numbers, bank accounts, fraud scores
    }
    
    /**
     * InventoryReserved Integration Event
     * 
     * Published by: Inventory context
     * Consumed by: Orders, Shipping
     */
    export interface InventoryReserved_V1 extends IntegrationEventBase {
        eventType: 'inventory.InventoryReserved';
        eventVersion: 1;
        
        reservationId: string;
        orderId: string;
        
        items: Array<{
            productId: string;
            quantity: number;
            warehouseId: string;  // Shipping needs to know where to pick
        }>;
        
        expectedPickDate: string;
    }
}
 
/**
 * Schema documentation - critical for integration events
 */
const OrderPlacedDocs = {
    eventType: 'orders.OrderPlaced',
    version: 1,
    description: 'Published when a customer successfully places an order',
    producer: 'Orders Service',
    consumers: ['Shipping Service', 'Analytics Service', 'Loyalty Service'],
    guarantees: {
        delivery: 'At least once, within 5 minutes of order placement',
        ordering: 'No ordering guarantees across different orders',
    },
    breaking_changes: {
        policy: 'Never remove fields; deprecate and add new version',
        deprecation: '3 month notice before removing deprecated fields',
    },
    schema_evolution: {
        v1: 'Initial version (2023-01-01)',
        v2: 'Added customer.loyaltyPoints (2024-03-15)',
    },
};

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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

/**
 * Anti-Corruption Layer Pattern
 * 
 * The Shipping context translates Orders context events
 * into its own domain language.
 */
namespace OrdersContext {
    // Orders context uses 'Order' and 'OrderItem'
    export interface OrderPlaced {
        orderId: string;
        customerId: string;
        items: Array<{
            productId: string;
            quantity: number;
            unitPrice: number;
        }>;
        shippingAddress: Address;
    }
}
 
namespace ShippingContext {
    // Shipping context uses 'Shipment' and 'Package'
    interface Shipment {
        shipmentId: string;
        orderId: string;  // Reference to Orders context
        recipient: Recipient;
        packages: Package[];
        status: ShipmentStatus;
    }
    
    interface Package {
        packageId: string;
        items: PackageItem[];
        weight: Weight;
        dimensions: Dimensions;
    }
    
    /**
     * Anti-Corruption Layer: Translates OrderPlaced to Shipment
     */
    class OrderEventTranslator {
        constructor(
            private productCatalog: ProductCatalog,
            private packingService: PackingService,
        ) {}
        
        async translateOrderPlaced(
            event: OrdersContext.OrderPlaced
        ): Promise<CreateShipmentCommand> {
            // Translate Order items to Package items
            const packageItems = await Promise.all(
                event.items.map(async (item) => {
                    const product = await this.productCatalog.findById(
                        item.productId
                    );
                    
                    return {
                        productId: item.productId,
                        quantity: item.quantity,
                        weight: product.shippingWeight,
                        dimensions: product.shippingDimensions,
                        isFragile: product.isFragile,
                    };
                })
            );
            
            // Determine optimal packaging
            const packages = await this.packingService.planPackages(
                packageItems
            );
            
            // Translate address to Recipient
            const recipient = this.translateAddress(event.shippingAddress);
            
            // Return command in Shipping context language
            return new CreateShipmentCommand({
                orderId: event.orderId,
                recipient,
                packages,
                priority: this.determinePriority(event),
            });
        }
        
        private translateAddress(address: Address): Recipient {
            return {
                name: address.fullName,
                address: {
                    line1: address.street,
                    line2: address.apartment,
                    city: address.city,
                    state: address.state,
                    postalCode: address.postalCode,
                    country: address.country,
                },
                phone: address.phone,
            };
        }
    }
    
    /**
     * Event handler that uses the translator
     */
    class OrderPlacedHandler {
        constructor(
            private translator: OrderEventTranslator,
            private commandBus: CommandBus,
        ) {}
        
        async handle(event: OrdersContext.OrderPlaced): Promise<void> {
            // Translate external event to internal command
            const command = await this.translator.translateOrderPlaced(event);
            
            // Execute in Shipping context's own language
            await this.commandBus.dispatch(command);
        }
    }
}
 
/**
 * Published Language Pattern
 * 
 * Multiple contexts agree on a shared event schema for analytics.
 */
namespace SharedLanguage {
    /**
     * Common transaction event that all contexts publish.
     * Defined collaboratively by Orders, Payments, Shipping teams.
     */
    export interface TransactionEvent {
        transactionId: string;
        transactionType: 'ORDER' | 'PAYMENT' | 'SHIPMENT' | 'REFUND';
        timestamp: string;
        amount?: {
            value: number;
            currency: string;
        };
        customerId: string;
        
        // Common dimensions for analytics
        dimensions: {
            region: string;
            segment: string;
            channel: string;
        };
    }
    
    // Each context translates its events to this shared format
    // before publishing to the analytics queue
}

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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

/**
 * Pattern: Event Notification
 * 
 * Thin events that trigger consumers to fetch more data.
 */
// Orders publishes thin event
const orderPlacedNotification = {
    eventType: 'orders.OrderPlaced',
    orderId: 'order-123',
    occurredAt: '2024-01-15T10:00:00Z',
    // No order details - just notification
};
 
// Consumer fetches details if needed
class ShippingEventHandler {
    async handleOrderPlaced(event: OrderPlacedNotification): Promise<void> {
        // Call back to Orders service for full details
        const orderDetails = await this.ordersApi.getOrder(event.orderId);
        
        await this.createShipment(orderDetails);
    }
}
 
/**
 * Pattern: Event-Carried State Transfer
 * 
 * Rich events that provide all needed context.
 */
// Orders publishes rich event
const orderPlacedFull = {
    eventType: 'orders.OrderPlaced',
    orderId: 'order-123',
    occurredAt: '2024-01-15T10:00:00Z',
    customer: {
        id: 'cust-456',
        email: 'customer@example.com',
        tier: 'GOLD',
    },
    items: [
        { productId: 'prod-1', quantity: 2, weight: 1.5 },
        { productId: 'prod-2', quantity: 1, weight: 0.5 },
    ],
    shippingAddress: {
        /* full address */
    },
    // All data shipping needs
};
 
// Consumer processes without callback
class ShippingEventHandlerAutonomous {
    async handleOrderPlaced(event: OrderPlacedFull): Promise<void> {
        // No external calls needed - all data in event
        await this.createShipment({
            orderId: event.orderId,
            recipient: event.customer.email,
            items: event.items,
            address: event.shippingAddress,
        });
    }
}
 
/**
 * Pattern: Choreography
 * 
 * Services react to events independently, no central coordinator.
 */
// OrderPlaced triggers independent reactions:
 
// Inventory Service
class InventoryService {
    @EventHandler('orders.OrderPlaced')
    async reserveStock(event: OrderPlaced): Promise<void> {
        for (const item of event.items) {
            await this.inventory.reserve(item.productId, item.quantity);
        }
        // Publishes: inventory.StockReserved
    }
}
 
// Payment Service
class PaymentService {
    @EventHandler('orders.OrderPlaced')
    async initiatePayment(event: OrderPlaced): Promise<void> {
        await this.payments.charge(event.customerId, event.orderTotal);
        // Publishes: payments.PaymentReceived or payments.PaymentFailed
    }
}
 
// Notification Service
class NotificationService {
    @EventHandler('orders.OrderPlaced')
    async sendConfirmation(event: OrderPlaced): Promise<void> {
        await this.email.send({
            to: event.customer.email,
            template: 'order-confirmation',
            data: event,
        });
    }
}
 
/**
 * Pattern: Saga / Process Manager
 * 
 * Central coordinator for complex workflows requiring compensation.
 */
class OrderFulfillmentSaga {
    private state: SagaState;
    
    @Handles('orders.OrderPlaced')
    async start(event: OrderPlaced): Promise<void> {
        this.state = {
            orderId: event.orderId,
            status: 'STARTED',
            completedSteps: [],
        };
        
        // Start the workflow
        await this.commandBus.send(new ReserveInventoryCommand(
            event.orderId,
            event.items,
        ));
    }
    
    @Handles('inventory.StockReserved')
    async onStockReserved(event: StockReserved): Promise<void> {
        if (event.orderId !== this.state.orderId) return;
        
        this.state.completedSteps.push('INVENTORY_RESERVED');
        
        // Next step
        await this.commandBus.send(new ProcessPaymentCommand(
            this.state.orderId,
        ));
    }
    
    @Handles('payments.PaymentReceived')
    async onPaymentReceived(event: PaymentReceived): Promise<void> {
        if (event.orderId !== this.state.orderId) return;
        
        this.state.completedSteps.push('PAYMENT_PROCESSED');
        
        // Next step
        await this.commandBus.send(new CreateShipmentCommand(
            this.state.orderId,
        ));
    }
    
    @Handles('payments.PaymentFailed')
    async onPaymentFailed(event: PaymentFailed): Promise<void> {
        if (event.orderId !== this.state.orderId) return;
        
        // Compensating action: release inventory
        await this.commandBus.send(new ReleaseInventoryCommand(
            this.state.orderId,
        ));
        
        // Compensating action: cancel order
        await this.commandBus.send(new CancelOrderCommand(
            this.state.orderId,
            'PAYMENT_FAILED',
        ));
        
        this.state.status = 'FAILED';
    }
}

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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

/**
 * Designing for Eventual Consistency
 */
 
// 1. ACCEPT PROCESSING STATES
enum OrderStatus {
    PLACED = 'PLACED',           // Order created, awaiting confirmation
    PAYMENT_PENDING = 'PAYMENT_PENDING',
    CONFIRMED = 'CONFIRMED',      // All downstream processing complete
    FAILED = 'FAILED',            // Some step failed
}
 
class Order {
    // Order can be in 'limbo' while downstream processes complete
    static place(/* ... */): Order {
        const order = new Order(/* ... */);
        order.status = OrderStatus.PLACED;  // Not CONFIRMED yet!
        
        order.addDomainEvent(new OrderPlaced(/* ... */));
        return order;
    }
    
    // Called when all downstream confirmations received
    confirm(): void {
        this.status = OrderStatus.CONFIRMED;
        this.addDomainEvent(new OrderConfirmed(/* ... */));
    }
}
 
// 2. COMPENSATING ACTIONS
class OrderEventHandlers {
    @Handles('payments.PaymentFailed')
    async handlePaymentFailed(event: PaymentFailed): Promise<void> {
        const order = await this.orderRepository.findById(event.orderId);
        
        // Compensate: release any reserved inventory
        order.markPaymentFailed(event.reason);
        
        // Emit compensation events
        order.addDomainEvent(new OrderPaymentFailed({
            orderId: event.orderId,
            reason: event.reason,
        }));
        
        // Inventory service will listen and release reservations
        // Email service will listen and notify customer
    }
}
 
// 3. SAGA TRACKING STATE
interface FulfillmentState {
    orderId: string;
    currentStep: FulfillmentStep;
    completedSteps: FulfillmentStep[];
    failedAt?: FulfillmentStep;
    compensatedSteps: FulfillmentStep[];
}
 
class OrderFulfillmentSaga {
    async handleStepFailure(
        orderId: string,
        failedStep: FulfillmentStep,
    ): Promise<void> {
        const state = await this.sagaRepository.find(orderId);
        state.failedAt = failedStep;
        
        // Compensate completed steps in reverse order
        const stepsToCompensate = [...state.completedSteps].reverse();
        
        for (const step of stepsToCompensate) {
            await this.compensate(step, state);
            state.compensatedSteps.push(step);
        }
        
        await this.sagaRepository.save(state);
    }
    
    private async compensate(
        step: FulfillmentStep,
        state: FulfillmentState,
    ): Promise<void> {
        switch (step) {
            case 'INVENTORY_RESERVED':
                await this.commandBus.send(
                    new ReleaseInventoryCommand(state.orderId)
                );
                break;
            case 'PAYMENT_CAPTURED':
                await this.commandBus.send(
                    new RefundPaymentCommand(state.orderId)
                );
                break;
            // ... other compensations
        }
    }
}
 
// 4. OPTIMISTIC UI
class OrderPlacementUI {
    async placeOrder(orderData: OrderData): Promise<void> {
        // Immediately show optimistic result
        this.displayOptimisticOrder({
            ...orderData,
            status: 'PROCESSING',
            message: 'Your order is being confirmed...',
        });
        
        try {
            const order = await this.ordersApi.placeOrder(orderData);
            
            // Poll or use WebSocket for real updates
            this.subscribeToOrderUpdates(order.id, (update) => {
                this.displayOrderUpdate(update);
            });
            
        } catch (error) {
            // Correct the optimistic update
            this.displayOrderError(error);
        }
    }
}

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

/**
 * CloudEvents-compatible event format
 * 
 * Standard format for interoperability between different systems.
 * https://cloudevents.io
 */
interface CloudEvent<T> {
    // Required
    specversion: '1.0';           // CloudEvents spec version
    type: string;                  // Event type (e.g., 'orders.OrderPlaced')
    source: string;                // Event source (e.g., '/orders-service')
    id: string;                    // Unique event ID
    
    // Optional but recommended
    time?: string;                 // ISO-8601 timestamp
    datacontenttype?: string;      // 'application/json'
    subject?: string;              // Subject of event (e.g., order ID)
    
    // Extension attributes
    correlationid?: string;        // Custom extension
    causationid?: string;          // Custom extension
    
    // Event data (your domain payload)
    data?: T;
}
 
/**
 * Example: Publishing with CloudEvents format
 */
function createOrderPlacedCloudEvent(
    order: Order,
    correlationId: string,
): CloudEvent<OrderPlacedPayload> {
    return {
        specversion: '1.0',
        type: 'orders.OrderPlaced',
        source: '/orders-service',
        id: generateUUID(),
        time: new Date().toISOString(),
        datacontenttype: 'application/json',
        subject: order.id,
        correlationid: correlationId,
        data: {
            orderId: order.id,
            customerId: order.customerId,
            totalAmount: order.totalAmount.toDTO(),
            itemCount: order.items.length,
        },
    };
}
 
/**
 * Schema Registry for evolution management
 */
interface SchemaRegistry {
    register(eventType: string, schema: JSONSchema): number;  // Returns version
    getSchema(eventType: string, version: number): JSONSchema;
    getLatestSchema(eventType: string): JSONSchema;
    validateEvent(event: unknown, eventType: string): ValidationResult;
}
 
class KafkaEventPublisher {
    constructor(
        private kafka: KafkaClient,
        private schemaRegistry: SchemaRegistry,
    ) {}
    
    async publish<T>(
        topic: string,
        event: CloudEvent<T>,
    ): Promise<void> {
        // Validate against schema
        const validation = await this.schemaRegistry.validateEvent(
            event,
            event.type,
        );
        
        if (!validation.valid) {
            throw new SchemaValidationError(event.type, validation.errors);
        }
        
        // Serialize
        const serialized = JSON.stringify(event);
        
        // Publish with key for partitioning (ensures ordering per aggregate)
        await this.kafka.send({
            topic,
            messages: [{
                key: event.subject,  // Order ID for ordering
                value: serialized,
                headers: {
                    'content-type': 'application/json',
                    'ce-type': event.type,
                    'ce-source': event.source,
                },
            }],
        });
    }
}

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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

/**
 * Event Catalog Schema
 * 
 * Documents all integration events for discoverability and governance.
 */
interface EventCatalogEntry {
    // Identity
    eventType: string;
    namespace: string;
    currentVersion: number;
    
    // Ownership
    owner: {
        team: string;
        contact: string;
        repository: string;
    };
    
    // Documentation
    description: string;
    businessContext: string;
    examplePayload: object;
    
    // Schema
    schema: JSONSchema;
    previousVersions: Array<{
        version: number;
        schema: JSONSchema;
        deprecatedAt?: string;
        removedAt?: string;
    }>;
    
    // Relationships
    producer: ServiceInfo;
    consumers: ServiceInfo[];
    
    // Operational
    averageVolumePerDay: number;
    sla: {
        deliveryLatency: string;  // e.g., '< 1 second'
        availability: string;     // e.g., '99.9%'
    };
    
    // Lifecycle
    status: 'active' | 'deprecated' | 'retired';
    createdAt: string;
    deprecatedAt?: string;
    retireAt?: string;
}
 
/**
 * AsyncAPI specification for event documentation
 * 
 * Industry standard for event-driven API documentation.
 */
const ordersServiceAsyncAPI = {
    asyncapi: '2.6.0',
    info: {
        title: 'Orders Service Events',
        version: '1.0.0',
        description: 'Events published by the Orders bounded context',
    },
    channels: {
        'orders.events': {
            publish: {
                summary: 'Order lifecycle events',
                message: {
                    oneOf: [
                        { '$ref': '#/components/messages/OrderPlaced' },
                        { '$ref': '#/components/messages/OrderShipped' },
                        { '$ref': '#/components/messages/OrderCancelled' },
                    ],
                },
            },
        },
    },
    components: {
        messages: {
            OrderPlaced: {
                name: 'OrderPlaced',
                title: 'Order Placed',
                summary: 'Published when a customer places an order',
                payload: {
                    type: 'object',
                    properties: {
                        eventType: { const: 'orders.OrderPlaced' },
                        eventVersion: { const: 1 },
                        orderId: { type: 'string', format: 'uuid' },
                        customerId: { type: 'string' },
                        orderTotal: { '$ref': '#/components/schemas/Money' },
                    },
                    required: ['eventType', 'orderId', 'customerId'],
                },
            },
        },
        schemas: {
            Money: {
                type: 'object',
                properties: {
                    amount: { type: 'number' },
                    currency: { type: 'string', pattern: '^[A-Z]{3}$' },
                },
            },
        },
    },
};
 
/**
 * Automated compatibility check for event changes
 */
class EventCompatibilityChecker {
    checkBreakingChanges(
        oldSchema: JSONSchema,
        newSchema: JSONSchema,
    ): BreakingChange[] {
        const changes: BreakingChange[] = [];
        
        // Check for removed required fields
        const oldRequired = new Set(oldSchema.required || []);
        const newRequired = new Set(newSchema.required || []);
        
        for (const field of oldRequired) {
            if (!newSchema.properties?.[field]) {
                changes.push({
                    type: 'REMOVED_FIELD',
                    field,
                    severity: 'BREAKING',
                    message: `Required field '${field}' was removed`,
                });
            }
        }
        
        // Check for type changes
        for (const [field, oldProp] of Object.entries(oldSchema.properties || {})) {
            const newProp = newSchema.properties?.[field];
            if (newProp && oldProp.type !== newProp.type) {
                changes.push({
                    type: 'TYPE_CHANGE',
                    field,
                    severity: 'BREAKING',
                    message: `Field '${field}' changed from ${oldProp.type} to ${newProp.type}`,
                });
            }
        }
        
        return changes;
    }
}