Build read models and projections from event streams

Projection patterns

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

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.

---
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

Overview

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

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill projection-patterns -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/backend-development/skills/projection-patterns

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/74130345d97629c58bd1/projection-patterns.zip" -OutFile "$env:TEMP\projection-patterns.zip"; Expand-Archive "$env:TEMP\projection-patterns.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md2.6 KB
references/1 file · 13.9 KB

Read the files here

wshobson/4236bb92 files

SKILL.md2.6 KB

SKILL.md

Show the full text63 lines

projection-patterns/SKILL.md63 lines · 2.6 KB

PreviewCode

Outline

RawView on GitHub

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

1	---
2	name: projection-patterns
3	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.
4	---
5
6	# Projection Patterns
7
8	Comprehensive guide to building projections and read models for event-sourced systems.
9
10	## When to Use This Skill
11
12	- Building CQRS read models
13	- Creating materialized views from events
14	- Optimizing query performance
15	- Implementing real-time dashboards
16	- Building search indexes from events
17	- Aggregating data across streams
18
19	## Core Concepts
20
21	### 1. Projection Architecture
22
23	```
24	┌─────────────┐ ┌─────────────┐ ┌─────────────┐
25	│ Event Store │────►│ Projector │────►│ Read Model │
26	│ │ │ │ │ (Database) │
27	│ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │
28	│ │ Events │ │ │ │ Handler │ │ │ │ Tables │ │
29	│ └─────────┘ │ │ │ Logic │ │ │ │ Views │ │
30	│ │ │ └─────────┘ │ │ │ Cache │ │
31	└─────────────┘ └─────────────┘ └─────────────┘
32	```
33
34	### 2. Projection Types
35
36	\| Type \| Description \| Use Case \|
37	\| -------------- \| --------------------------- \| ---------------------- \|
38	\| Live \| Real-time from subscription \| Current state queries \|
39	\| Catchup \| Process historical events \| Rebuilding read models \|
40	\| Persistent \| Stores checkpoint \| Resume after restart \|
41	\| Inline \| Same transaction as write \| Strong consistency \|
42
43	## Templates and detailed worked examples
44
45	Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
46
47	## Best Practices
48
49	### Do's
50
51	- Make projections idempotent - Safe to replay
52	- Use transactions - For multi-table updates
53	- Store checkpoints - Resume after failures
54	- Monitor lag - Alert on projection delays
55	- Plan for rebuilds - Design for reconstruction
56
57	### Don'ts
58
59	- Don't couple projections - Each is independent
60	- Don't skip error handling - Log and alert on failures
61	- Don't ignore ordering - Events must be processed in order
62	- Don't over-normalize - Denormalize for query patterns
63