tomevault-io 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_docswith technology:event-drivenfor 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
Source: claude-dev-suite/claude-dev-suite — distributed by TomeVault.