SKILL.md
CQRS and Event Sourcing Patterns
Expert guidance for implementing Command Query Responsibility Segregation (CQRS) and Event Sourcing patterns to build scalable, auditable systems with complete historical tracking and optimized read/write models.
When to Use This Skill
- Building systems requiring complete audit trails and compliance
- Implementing temporal queries ("show me the state at time T")
- Designing high-scale applications with complex domain logic
- Creating systems with significantly different read and write patterns
- Building event-driven architectures with historical replay capability
- Implementing systems requiring multiple read model projections
- Designing applications where understanding "what happened" is critical
- Building collaborative systems with conflict resolution needs
Core Principles
1. Command Query Separation
Separate operations that change state (commands) from operations that read state (queries).
| Commands (Write) | Queries (Read) |
|---|---|
| Express intent (CreateOrder, UpdatePrice) | Return data, never change state |
| Can be rejected (validation failures) | Can be cached and optimized |
| Return success/failure, not data | Multiple models for different needs |
| Change system state | Eventually consistent with writes |
2. Events as Source of Truth
Store state changes as immutable events rather than current state snapshots.
Traditional: Store what IS → UPDATE users SET email = '[email protected]' Event Sourcing: Store what HAPPENED → APPEND UserEmailChanged event
Result: Complete history, temporal queries, audit trail
3. Eventual Consistency
Accept temporary inconsistency between write and read models for scalability.
4. Domain-Driven Design Integration
- Aggregates enforce business invariants
- Events represent domain facts
- Commands express domain operations
- Bounded contexts define consistency boundaries
Quick Reference
| Task | Load reference |
|---|---|
| CQRS implementation patterns | skills/cqrs-event-sourcing/references/cqrs-patterns.md |
| Event sourcing & snapshots | skills/cqrs-event-sourcing/references/event-sourcing.md |
| EventStoreDB & Axon Framework | skills/cqrs-event-sourcing/references/event-store-tech.md |
| Consistency patterns | skills/cqrs-event-sourcing/references/consistency-patterns.md |
| Best practices checklist | skills/cqrs-event-sourcing/references/best-practices.md |
Workflow
- Identify if CQRS/ES is appropriate (high audit, temporal, or scale needs)
- Design commands expressing user intent
- Define events as immutable facts (past tense naming)
- Implement aggregates as consistency boundaries
- Create projections optimized for specific query needs
- Handle eventual consistency across bounded contexts
Common Mistakes
- Using CQRS for simple CRUD applications (overkill)
- Large aggregates that span multiple consistency boundaries
- Modifying or deleting events after publication
- Skipping command validation before aggregate processing
- Missing idempotency in event handlers
- No versioning strategy for event schema evolution
- Tight coupling between aggregates (use ID references only)
Resources
- Books: "Implementing Domain-Driven Design" (Vernon), "Event Sourcing & CQRS" (Betts et al)
- Sites: cqrs.wordpress.com, eventstore.com/blog, axoniq.io/resources
- Tools: EventStoreDB, Axon Framework, Marten, Eventuous
- Patterns: Event Sourcing, CQRS, Process Manager, Saga, Snapshot