Projections

## What a projection is **CQRS** (Command Query Responsibility Segregation) splits a system's write path (commands, which mutate state through an aggregate/domain model enforcing invariants) from its read path (queries, which just need to answer questions fast). A **projection** is the concrete artifact on the read side: a specific, materialized read model built by subscribing to a stream of events emitted whenever the write side commits a change, and applying those events to a store shaped for one particular access pattern. It's called a 'projection' because it takes the full richness of the event history and projects it down into whatever narrow shape a given query actually needs — much like a mathematical projection reduces a higher-dimensional object onto a simpler plane. ## How one is actually driven Mechanically, a projection is driven by a **handler**: a piece of code subscribed to an event stream (a message broker topic, an event store's subscription API, or an outbox table being polled). For every event it receives — say, `OrderPlaced` or `OrderCancelled` — it applies a transformation into its store: - upsert a row - increment a counter - add a document to a search index It tracks a position or **checkpoint** (an offset, a sequence number) so that if it restarts, it knows where to resume rather than reprocessing everything or skipping events. The store underneath is whatever best fits the query: - a flat relational table for a dashboard - a document store matching an API response shape one-to-one - a search index for full-text lookup - a Redis counter for a live badge ## Why the two sides are split at all The reason this separation exists is that the write model and the read model have genuinely conflicting design pressures. The write model wants to be normalized, scoped to one aggregate per transaction, and structured to make invariants easy to enforce — it is not optimized to answer 'give me this customer's order history with totals, sorted, paginated, and filterable by status' efficiently. If you try to serve every read need from that same model, you either: - bloat it with query-specific fields it has no business owning, or - pay for expensive joins and aggregations on every request against the transactional store, competing with the writes themselves for capacity. Separating the two lets the read side scale independently — add read replicas, cache aggressively, pick a completely different storage engine — without ever touching the write model's schema or logic, and lets the read shape evolve freely as UI/API needs change. ## The central trade-off The central trade-off is **eventual consistency**. After a command commits, there is a window — often milliseconds, sometimes longer under load or backlog — before the projection reflects that change. Any caller reading from the projection during that window sees stale data. This forces explicit design decisions: does the UI need to see its own just-made change immediately (a 'read-your-writes' requirement), and if so, how is that satisfied? - by returning the result directly from the command response rather than re-querying, or - by having the client wait/poll until the projection reaches a known position Beyond consistency, adopting projections also means adopting more infrastructure: an event bus or subscription mechanism, one or more separate stores, and checkpoint tracking, all of which need monitoring and can fail independently of the write path. ## Failure modes in production In production, a handful of failure modes recur. 1. **Projection lag** spikes under load — the consumer falls behind the event stream, and users start noticing stale reads, sometimes without any alarm firing because 'it's still working, just slow.' 2. **Silent divergence** is a subtler failure: a bug in the handler mishandles one event type (say, an update event is treated like a create), and the projection quietly drifts from what the write side actually reflects, sometimes for a long time before anyone notices the numbers look wrong. 3. **Checkpoint loss** is another: if a consumer crashes and its last-committed position wasn't durably persisted, restart either reprocesses already-applied events (fine only if the handler is idempotent) or skips ahead and misses some. 4. A malformed or unexpectedly-shaped event can throw inside the handler and stall the whole consumer behind it — a **'poison message'** blocking everything queued after it. ## A worked example A concrete example: an e-commerce system's write side enforces order invariants (can't ship what wasn't paid, can't cancel what already shipped) through a normalized Orders write model. - A projection handler subscribed to `OrderPlaced/OrderShipped/OrderCancelled` maintains a denormalized `OrderSummary` table feeding the customer's dashboard. - A second, independent handler on the same events feeds an Elasticsearch index used by support agents to search orders by free text. - A third maintains a Redis counter for 'orders today' shown on an internal ops screen. Each projection is purpose-built, independently scalable, and disposable — if one has a bug, it can be fixed and rebuilt from history without touching the other two or the write model at all.