projection-patterns
wshobson/agents
Build read models and projections from event streams for CQRS and event-sourced systems.
What is projection-patterns?
Comprehensive guide to implementing projections and materialized views that transform event streams into optimized read models. Use this skill when building CQRS architectures, creating real-time dashboards, or optimizing query performance in event-sourced systems.
- Design projection architectures that consume event streams and populate read models
- Implement live, catchup, persistent, and inline projection types for different consistency requirements
- Create idempotent projections safe for replay and rebuilding
- Store checkpoints to resume processing after failures
- Build materialized views and search indexes from events
- Handle multi-table updates with transactions
How to install projection-patterns
npx skills add https://github.com/wshobson/agents --skill projection-patterns- Event store or event stream infrastructure
- Database or cache for storing read models
- Understanding of event sourcing concepts
How to use projection-patterns
- 1.Review projection types (live, catchup, persistent, inline) to choose the right pattern for your consistency requirements
- 2.Design your read model schema based on query patterns, denormalizing as needed
- 3.Implement projection handlers that transform events into read model updates
- 4.Add checkpoint storage to track processing progress and enable resumption
- 5.Set up monitoring to alert on projection lag or processing failures
- 6.Test idempotency by replaying projections multiple times
- 7.Plan and test rebuild procedures for reconstructing read models from events
Use cases
- Implementing CQRS read sides that serve optimized queries independently from the write model
- Creating real-time dashboards that update as events flow through the system
- Rebuilding materialized views and read models from historical event streams
- Building search indexes from domain events for fast text or faceted search
- Aggregating data across multiple event streams into denormalized views
- Backend engineers implementing event-sourced systems
- CQRS architects designing read and write model separation
- Database designers optimizing query performance
- System engineers building real-time data pipelines
projection-patterns FAQ
Live projections process events in real-time from a subscription, ideal for current state queries. Catchup projections process historical events from the beginning, used for rebuilding read models or catching up after downtime.
Idempotent projections can safely handle duplicate events or replays without corrupting data. This is essential for reliability when events may be delivered multiple times or when rebuilding read models.
Store checkpoints to track which events have been processed. On failure, resume from the last checkpoint rather than reprocessing all events. Log failures and alert operators for investigation.
Denormalize read models based on your query patterns. Unlike write models, read models optimize for query performance, not storage efficiency. Include all data needed for queries in a single table or view.
Yes, projections are independent. Multiple projections can subscribe to the same event stream and build different read models for different query patterns.
Full instructions (SKILL.md)
Source of truth, from wshobson/agents.
name: projection-patterns description: Build read models and projections from event streams. Use when implementing CQRS read sides, building materialized views, or optimizing query performance in event-sourced systems.
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
| Type | Description | Use Case |
|---|---|---|
| Live | Real-time from subscription | Current state queries |
| Catchup | Process historical events | Rebuilding read models |
| Persistent | Stores checkpoint | Resume after restart |
| Inline | Same transaction as write | Strong consistency |
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.
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
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
Related skills
More from wshobson/agents and the wider catalog.
prometheus-configuration
Set up Prometheus for comprehensive metric collection, storage, and monitoring of infrastructure and applications.
prompt-engineering-patterns
Master advanced prompt engineering techniques to maximize LLM performance and reliability.
protect-mcp-setup
Cryptographic policy enforcement and Ed25519-signed audit receipts for Claude Code tool calls.
protocol-reverse-engineering
Capture, analyze, and document network protocols for security research and debugging.
python-anti-patterns
Checklist of common Python anti-patterns to catch before code review and deployment.
python-background-jobs
Async task queues and background job patterns for decoupling long-running work from request/response cycles.