Skip to content
API Design Learn/Event-Driven APIs
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

CQRS & Event Sourcing

4 min read

You'll learn to

  • -Tell CQRS (separate write and read models) from event sourcing (store events, derive state)
  • -Replay an event log to get a balance and an earlier balance, and build a read model from it
  • -Decide how an API handles the moment when a client reads before the read model has caught up

These two patterns are often mentioned together and compose well, but they solve different problems. CQRS is about separating how you write from how you read. Event sourcing is about how you store state in the first place. This chapter builds on the CQRS and event sourcing chapters from the LLD schema track, applied here to API and service design.

An Analogy: The Ledger and the Notice Board

A shop keeps a ledger in which every sale and refund is written down, never erased. That is event sourcing: the truth is the list of things that happened. The shop also pins today's takings on a notice board by the door, updated at the end of each sale. That is a read model: a summary built from the ledger for quick reading, which is sometimes a moment behind it. Using separate things for writing and for reading is CQRS.

CQRS: Separate Models for Writes and Reads

Command Query Responsibility Segregation splits an API's write path (commands, which change state) from its read path (queries, which fetch data), so each can be tuned on its own. The write model may be normalized and transaction-safe. The read model may be heavily denormalized and pre-joined for the queries clients actually make. It is the write-optimized versus read-optimized trade-off from the schema chapter, expressed here as two API surfaces, or even two services, instead of two database schemas.

Event Sourcing: State as a Sequence of Events

Current state derived from a sequence of events, not stored directly
[
  {"event": "AccountOpened", "account_id": 42, "initial_balance": 0},
  {"event": "FundsDeposited", "account_id": 42, "amount": 100},
  {"event": "FundsWithdrawn", "account_id": 42, "amount": 30}
]
// current balance = replay every event in order: 0 + 100 - 30 = 70
// NOT stored as a single mutable "balance: 70" row anywhere

Instead of storing only the current state and overwriting it, event sourcing stores every state-changing event, and derives the current state by replaying them. That keeps the complete history for free, which is the append-only ledger idea from financial modeling. It also lets one event log feed several read models, built in different ways and rebuilt whenever needed. That is where event sourcing and CQRS meet: the write side appends events, and independent read models are built by replaying them.

The demo does all of it on the bank-account log above. It replays the events to get a balance, and a balance as of earlier. It then builds a read model, adds a new deposit, and shows the gap before the read model catches up.

Press Run: replay gives the truth and its history; the read model is briefly behind

The API-Design Question: Eventual Consistency

Because the read model is built from events asynchronously, a client that has just issued a command and immediately queries may not see its own change yet. That is a real design decision, not an implementation detail. You can accept the window and design the client around it, for example with an optimistic update that shows the change at once on screen. Or you can let the client read its own writes: route that particular read through the write model, or return enough in the command's own response, as the demo does, that no follow-up read is needed right away.

CQRS and event sourcing are real complexity: two models to keep apart, an event log to design and maintain, and a consistency window every client flow must handle. They earn their place in read-heavy systems with very different read and write patterns, or where full history is a hard requirement. They are not the default for a typical CRUD service.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design CQRS Command Center in the API Design Lab's gRPC & Event-Driven act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!