home / skills / sickn33 / antigravity-awesome-skills / projection-patterns

projection-patterns skill

safe

This skill helps you design and implement projections and read models from event streams for CQRS, dashboards, and optimized queries.

This is most likely a fork of the projection-patterns skill from xfstudio

npx playbooks add skill sickn33/antigravity-awesome-skills --skill projection-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.0 KB

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

## Use this skill when

- 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

## Do not use this skill when

- The task is unrelated to projection patterns
- You need a different domain or tool outside this scope

## Instructions

- Clarify goals, constraints, and required inputs.
- Apply relevant best practices and validate outcomes.
- Provide actionable steps and verification.
- If detailed examples are required, open `resources/implementation-playbook.md`.

## Resources

- `resources/implementation-playbook.md` for detailed patterns and examples.

Overview

This skill helps design and implement projections and read models from event streams for event-sourced systems. It focuses on CQRS read sides, materialized views, and strategies to improve query performance and real-time aggregation. The goal is practical, production-ready patterns and verification steps you can apply in Python-based architectures.

How this skill works

The skill analyzes event shapes, access patterns, and latency requirements to recommend projection topologies and update semantics (e.g., incremental, idempotent, or upsert-based). It provides concrete mapping strategies from events to read models, selection of storage backends (key-value, relational, search index), and guidance to make updates resilient and testable. It also outlines verification and monitoring checks to ensure correctness and freshness.

When to use it

Implementing CQRS read models for a microservice or domain
Creating materialized views for dashboards or analytics from event streams
Building search indexes or denormalized tables from events
Optimizing read performance when queries are slow on the canonical store
Aggregating metrics or rollups across multiple event streams

Best practices

Clarify query shapes, SLAs, and ordering guarantees before designing projections
Design projections to be idempotent and replay-safe to recover from failures
Use partitioning and per-aggregate keys to scale projection workers horizontally
Choose storage optimized for the access pattern (e.g., Redis for low-latency, Postgres for complex queries, Elasticsearch for full-text)
Add monitoring for lag, error rate, and data divergence; include reconciliation jobs for drift

Example use cases

Real-time dashboard that aggregates user activity counts across services
Materialized read table for fast order lookups and reporting in an e-commerce system
Search index powered by domain events to enable full-text product search
Background projection worker that maintains per-customer summaries for personalization
Audit-friendly projection that stores historical snapshots for compliance queries

FAQ

How do I handle out-of-order events?

Design projections to be idempotent and include causal ordering metadata; use sequence numbers or vector clocks and buffering for strict ordering when required.

What if my projection gets corrupted?

Replay events from the origin to rebuild the projection, using a deterministic processor and a replay-safe output path; maintain reconciliation checks to detect corruption early.