Twelve in the system, nine on the shelf
A stock counter in a warehouse scans bin C-14 and finds nine boxes of SKU 4471, a pack of USB-C cables. The inventory system says twelve. The obvious question is the one the system cannot answer: where did the other three go? The stock table holds one row for the SKU, quantity = 12, and every receipt, pick and return of the last month overwrote that number in place. The row knows the answer to "how many?" and has forgotten every answer to "why?".
An audit table beside it helps, but it stays a side record: a trigger can log every change to the number, yet only the code that made the change knows why. Event Sourcing turns the design around: the changes themselves become the record, and the current quantity becomes something computed from them.
Write down what happened, not what is
Each change is stored as an event: an immutable fact, named in the past tense, carrying the data needed to understand it later. StockReceived {qty: 20}. ItemsPicked {qty: 6, order: 9104}. Naming events as facts rather than as commands is the convention Domain Event explains. The events for one thing, here SKU 4471 in one warehouse, form its stream, and streams live in an Event Store, a database the application only appends to: events are never updated, and in normal operation none is deleted. The quantity is no longer stored anywhere as the truth. It is the result of reading the stream from the first event and applying each one in order, which is called replaying it:
StockReceived {qty: 20}takes the quantity from 0 to 20.ItemsPicked {qty: 6, order: 9104}takes it to 14.ItemsReturned {qty: 1, order: 9071}takes it to 15.ItemsPicked {qty: 3, order: 9183}takes it to 12.
The stream cannot explain a theft it never saw. What it does is turn "where did they go?" into a list someone can check: every movement, when, for which order, from which handheld. Replaying the stream only up to a given date gives the quantity as the system knew it on that date, a question the row could never answer. When the count is reconciled, that is one more event, StockCounted {counted: 9, expected: 12}, which sets the quantity to 9 on replay and keeps the gap of three on record.
Two pickers reach for the last boxes
The business rules still have to hold. A picker cannot take three boxes when the stream adds up to two. The code that enforces that is the aggregate for the SKU: it loads the stream, replays it to the current quantity, checks the command against it and appends the new event. Two handhelds can run that sequence at the same moment:
- Handheld A loads the stream: eight events, quantity 2.
- Handheld B loads the same eight events, also quantity 2.
- Handheld A accepts a pick of 2 and appends
ItemsPicked {qty: 2}as event 9. - Handheld B accepts its own pick of 2 and appends another
ItemsPicked {qty: 2}.
Without a guard, the stream now adds up to −2. The guard is an expected version on every append. A writes event 9 on the condition that the stream still ends at event 8, and the store accepts it. B's append carries the same condition, but the stream now ends at 9, so the store rejects it; B reloads, replays nine events, finds zero and refuses the pick. Event stores commonly accept this condition on an append (EventStoreDB calls it the expected revision); in a relational table, a unique constraint on (stream id, version) produces the same refusal. The check covers one stream, so a stream must hold everything one rule must see together, and no more: one SKU in one warehouse, not the whole warehouse, or every pick in the building would compete for the same version number.
The aggregate rebuilds SKU 4471 from its stream before it decides; the append succeeds only if nobody appended first.
Nobody replays the warehouse to draw a dashboard
Replaying one SKU's few hundred events before a pick is cheap. Replaying every stream in the warehouse to answer "which SKUs are below their reorder point?" is not, and the event store is organised by stream and position, not by quantity or bin. Reads come from projections. A projector follows the events as they are appended and keeps a table shaped for one question up to date: stock_on_hand for the dashboards, moves_per_order for the support team, as in the diagram.
A projection is disposable. If its code had a bug, or a new question needs a new shape, you empty the table and replay every event through the corrected projector; the events are the truth, and the projection is one way of reading them, kept ready. Two consequences come with that. A projection updated asynchronously, as events arrive, trails the store, so a page that reads stock_on_hand right after a pick may not show it yet; running the read side as a separate model is what CQRS covers, and precomputed query tables in general are Materialized View. And querying or joining the event store directly, instead of deriving a read model through a projection, is a common way this pattern decays: the append-only log becomes an ad-hoc database that every report depends on, and the format of its events can no longer change without breaking them.
The aggregate's own replay grows too. A SKU that has moved every day for five years has thousands of events, and loading all of them before each pick adds up. The usual remedy is to save the aggregate's state every so many events and replay only what came after; Snapshot covers when that is worth its cost.
The events outlive the code
Immutability is the point, and it charges something the row never did. A mistake cannot be edited away. If a scanner recorded ItemsPicked {qty: 30} where the picker took 3, that event stays in the stream, and a correcting event that names it, say PickCorrected {corrects: 57, recorded: 30, actual: 3}, is appended after it; on replay it puts the 27 boxes back. The history then shows both the error and its fix, which an auditor wants and whoever writes the correction logic has to plan for.
The format is permanent too. Two years in, ItemsPicked needs a bin field it never had. The store holds thousands of old ItemsPicked events without one, and the new code will replay them every time a projection is rebuilt. So event types usually carry a version, and the code reads every version that was ever written: a new field arrives optional, with a defined default that invents nothing (for an old pick's bin, unknown rather than a guessed location), and an old event is usually converted to the current shape as it is read, a step called upcasting, rather than rewritten in the store. Renaming a field or changing what it means in place is a breaking change to an API whose oldest callers are the history itself, and the history cannot be redeployed. Schema evolution: event formats & compatibility shows which changes stay compatible and how a registry checks them before they ship.
And because nothing is deleted, personal data inside events needs a plan before the first event is written, not after the first request to erase it. Deleting a person's data: erasure across every copy covers the options, crypto-shredding among them.
When a row is the better record
Event Sourcing earns its cost where the history belongs to the domain: stock, ledgers, orders, anything someone will reconcile or audit. For a user's display name, where nobody will ask why the value changed, it buys two models, a lagging projection and a versioning discipline in exchange for a history nobody reads.
Other services can subscribe to the stored events themselves; a service that keeps its state in rows and must publish events about it has a different problem, which Transactional Outbox solves. And the log a database keeps for its own crash recovery is a different log again, explained in Write-Ahead Log.
Where every arrow should point
The Event Sourcing challenge asks for this design without the warehouse. Its test is the direction of the arrows: state is written in one place, the Event Store, and everything else reads from it. A command reaches an aggregate that rebuilds itself from its stream before appending; a projector turns the stream into a read model; subscribers hear the same events through an Event Bus. An arrow that writes current state the stream cannot rebuild means the design has quietly gone back to the stock table. Event Sourcing: Snapshots & Projections picks up where this article points away: snapshots on the rebuild path, and a projection rebuilt from nothing by replaying history.