d-subrahmanyam/event-driven

Event-Driven Architecture Core Knowledge

Full Reference: See advanced.md for Saga implementations (Node.js, Java), Outbox pattern implementations, Event Sourcing, CQRS, and idempotency patterns.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: event-driven for comprehensive documentation.

When NOT to Use This Skill

• Monolithic applications - Use simple in-process events
• Simple CRUD operations - Use REST APIs or GraphQL
• Real-time UI updates - Use WebSockets or SSE
• Synchronous workflows - Use traditional transactions

Architecture Patterns Overview

| Pattern | Purpose | Complexity | |---------|---------|------------| | Pub/Sub | Decouple producers from consumers | Low | | Event Sourcing | Store state as event sequence | High | | CQRS | Separate read/write models | Medium-High | | Saga | Distributed transactions | High | | Outbox | Reliable event publishing | Medium |

Saga Pattern

Manages distributed transactions across services without 2PC.

Choreography Saga

┌─────────┐    event    ┌─────────┐    event    ┌─────────┐
│Order Svc│────────────▶│Payment  │────────────▶│Inventory│
└─────────┘             │   Svc   │             │   Svc   │
     ▲                  └─────────┘             └─────────┘
     │    compensate         │    compensate         │
     └───────────────────────┴───────────────────────┘

Orchestration Saga

                    ┌─────────────┐
                    │    Saga     │
                    │Orchestrator │
                    └─────────────┘
                    /      |      \
                   ▼       ▼       ▼
            ┌───────┐ ┌───────┐ ┌───────┐
            │Order  │ │Payment│ │Invent.│
            └───────┘ └───────┘ └───────┘

Transactional Outbox Pattern

Ensures reliable event publishing with database transactions.

┌────────────────────────────────────────────┐
│            Database Transaction            │
│  ┌──────────────┐    ┌──────────────────┐  │
│  │   Business   │    │   Outbox Table   │  │
│  │    Table     │    │   (messages)     │  │
│  └──────────────┘    └──────────────────┘  │
└────────────────────────────────────────────┘
                             │
                    Polling Relay / CDC
                             │
                    ┌─────────────────┐
                    │  Message Broker │
                    └─────────────────┘

Outbox Table Schema

CREATE TABLE outbox (
    id UUID PRIMARY KEY,
    aggregate_type VARCHAR(255) NOT NULL,
    aggregate_id VARCHAR(255) NOT NULL,
    event_type VARCHAR(255) NOT NULL,
    payload JSONB NOT NULL,
    status VARCHAR(50) DEFAULT 'PENDING',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CQRS Architecture

        Commands                          Queries
            │                                 │
            ▼                                 ▼
    ┌───────────────┐                ┌───────────────┐
    │ Command Model │                │  Query Model  │
    │   (Write)     │                │   (Read)      │
    └───────────────┘                └───────────────┘
            │                                 ▲
            ▼                                 │
    ┌───────────────┐     Events     ┌───────────────┐
    │  Write Store  │───────────────▶│  Read Store   │
    └───────────────┘                └───────────────┘

Anti-Patterns

| Anti-Pattern | Why It's Bad | Solution | |--------------|--------------|----------| | Event Soup | Too many fine-grained events | Design coarse-grained domain events | | Missing Idempotency | Duplicate processing | Add idempotency keys | | No Compensation Logic | Failed saga can't rollback | Implement compensating transactions | | No Dead Letter Queue | Failed events lost | Configure DLQ for error handling | | Weak Event Ordering | Race conditions | Use partitioning or ordered queues |

Quick Troubleshooting

| Issue | Diagnostic | Solution | |-------|------------|----------| | Lost events | Check message broker | Implement Outbox pattern | | Duplicate processing | Logs show multiple executions | Add idempotency checks | | Saga stuck | Compensation not triggered | Add timeout handling | | Growing DLQ | Many failed messages | Analyze failures, fix consumers | | Slow event processing | High message lag | Scale consumers, optimize handlers |

Best Practices

Message Design

• Include correlation ID for tracing
• Version your events for evolution
• Keep payloads small, reference large data

Error Handling

• Implement retry with exponential backoff
• Use Dead Letter Queues for failed messages
• Set up alerting on DLQ growth

Monitoring

• Track message lag
• Monitor consumer group health
• Alert on processing errors
• Trace message flow across services

Reference Documentation

Available topics: patterns, saga, outbox, cqrs