projection-patterns

Projection Patterns

Comprehensive guide to building projections and read models for event-sourced systems.

When to Use This Skill

• Building CQRS read models
• Creating materialized views from events
• Optimizing query performance
• Implementing real-time dashboards
• Building search indexes from events
• Aggregating data across streams

Core Concepts

1. Projection Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Event Store │────►│ Projector   │────►│ Read Model  │
│             │     │             │     │ (Database)  │
│ ┌─────────┐ │     │ ┌─────────┐ │     │ ┌─────────┐ │
│ │ Events  │ │     │ │ Handler │ │     │ │ Tables  │ │
│ └─────────┘ │     │ │ Logic   │ │     │ │ Views   │ │
│             │     │ └─────────┘ │     │ │ Cache   │ │
└─────────────┘     └─────────────┘     └─────────────┘

2. Projection Types

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates. Treat these templates as illustrative code to adapt and review before use, and have a person review or test any generated projector code before relying on it. This skill only needs read access to its bundled reference file.

Best Practices

Do's

• Make projections idempotent - Safe to replay
• Use transactions - For multi-table updates
• Store checkpoints - Resume after failures
• Monitor lag - Alert on projection delays
• Plan for rebuilds - Design for reconstruction; limit clearing during a rebuild to the projection's own tables, and get explicit user confirmation before clearing any existing read model data
• Treat event payloads as untrusted input - Use parameterized queries and validate or escape event fields before writing to databases, caches, or search indexes

Don'ts

• Don't couple projections - Each is independent
• Don't skip error handling - Log and alert on failures
• Don't ignore ordering - Events must be processed in order
• Don't over-normalize - Denormalize for query patterns