CQRS and Event Sourcing skill for Claude Code

Done well means: the team chose event sourcing for a concrete requirement it uniquely satisfies, appends are guarded by expected version, projections are idempotent and rebuildable from zero, the UI handles eventual consistency on purpose, and stored events are never edited.

Decide first

CQRS (separate write model and read models) and event sourcing (state stored as a sequence of events) are separate choices. Most systems that need one need only CQRS.

Requirement	Plain CRUD	CQRS, state-stored	Event sourcing
Simple forms over tables	Best	Overkill	Wrong
Read shapes very different from write shape, heavy read load	Views/replicas first	Good	Possible
Full audit of every business decision, legally required	Audit table	Audit table + outbox	Strong fit
Temporal queries (“what did we know on March 3?”)	Hard	Hard	Strong fit
Complex domain rules, many state transitions	Possible	Good	Good
Team new to the pattern, deadline in weeks	Best	OK	High risk

Event sourcing costs: schema evolution of immutable data, eventual consistency in every read, projection infrastructure, harder ad-hoc queries, and GDPR handling. Write down which row in the table above justifies it. If none does, stop and recommend a state-stored model with an outbox (event-driven-architecture covers that).

Scope it: event-source only the bounded contexts that need it (ledger, orders, claims), not the whole system.

Workflow

- [ ] 1. Record the justification and the bounded context in scope
- [ ] 2. Design events from the domain language, with metadata
- [ ] 3. Choose the event store; enforce per-stream optimistic concurrency
- [ ] 4. Implement aggregates as fold + decide
- [ ] 5. Build projections: idempotent, checkpointed, rebuildable
- [ ] 6. Handle consistency in the UI/API (read-your-writes)
- [ ] 7. Plan versioning, snapshots, and personal data
- [ ] 8. Test with given-when-then and a rebuild comparison

2. Event design

• Past-tense business facts: OrderPlaced, PaymentCaptured, ShipmentDispatched. Not OrderUpdated (no business meaning) and not commands (PlaceOrder).
• Each event carries what happened, not derived state that can be recomputed.
• Envelope metadata on every event:

{
  "eventId": "0192f3c4-...",
  "streamId": "order-8f3k",
  "streamVersion": 7,
  "type": "PaymentCaptured",
  "schemaVersion": 2,
  "occurredAt": "2026-03-14T09:26:53Z",
  "correlationId": "req-41ab",
  "causationId": "cmd-77c2",
  "actor": "user:123",
  "data": { "paymentId": "pay_19x", "amountCents": 4999, "currency": "EUR" }
}

• One stream per aggregate instance (order-<id>). Streams should stay short (tens to hundreds of events); a stream that grows without bound signals a modelling problem (see “closing the books” below).

3. Event store

Option	Use when
Postgres table you own	Moderate volume, team knows Postgres, wants one database
Marten (.NET on Postgres), Axon (JVM), Eventuous, Emmett (Node)	Framework fits the stack; handles projections and concurrency
EventStoreDB / KurrentDB	Dedicated store, persistent subscriptions, high stream counts
Kafka as the event store	Avoid: no per-stream optimistic concurrency, no cheap read of one stream

Non-negotiables for any store:

• Append with expected version; reject with a concurrency error if the stream moved. In Postgres: unique (stream_id, stream_version).
• A global, gap-safe read order for projections. A plain bigserial is not gap-safe: sequence values are allocated before commit, so a projection can read id 101, then a slower transaction commits id 100, which the projection never sees. Use a commit-ordered technique (see the reference) or a single writer.
• Publishing to other services goes through an outbox or the store’s subscription, never “append then publish” in application code.

For a complete Postgres schema, append function, gap-safe reading, and checkpoint tables, read references/postgres-event-store.md when building the store yourself.

4. Aggregates as fold + decide

type OrderEvent =
  | { type: "OrderPlaced"; data: { customerId: string; lines: Line[] } }
  | { type: "PaymentCaptured"; data: { paymentId: string; amountCents: number } }
  | { type: "OrderCancelled"; data: { reason: string } };

type OrderState = { status: "none" | "placed" | "paid" | "cancelled"; totalCents: number };

const initial: OrderState = { status: "none", totalCents: 0 };

function evolve(s: OrderState, e: OrderEvent): OrderState {
  switch (e.type) {
    case "OrderPlaced": return { status: "placed", totalCents: sum(e.data.lines) };
    case "PaymentCaptured": return { ...s, status: "paid" };
    case "OrderCancelled": return { ...s, status: "cancelled" };
  }
}

function decideCancel(s: OrderState, reason: string): OrderEvent[] {
  if (s.status === "none") throw new DomainError("order does not exist");
  if (s.status === "cancelled") return [];                 // idempotent no-op
  if (s.status === "paid") throw new DomainError("refund required before cancel");
  return [{ type: "OrderCancelled", data: { reason } }];
}

async function handleCancel(store: EventStore, orderId: string, reason: string) {
  const { events, version } = await store.readStream(`order-${orderId}`);
  const state = events.reduce(evolve, initial);
  const newEvents = decideCancel(state, reason);
  await store.append(`order-${orderId}`, newEvents, { expectedVersion: version });
}

• evolve is pure and never throws; it must accept every historical event shape.
• decide holds all business rules; it is where tests focus.
• On a concurrency error, reload and re-decide (bounded retries, 3 is typical), or return 409 to the caller.

5. Projections

• Each projection has a checkpoint (last processed global position). Update the read model and the checkpoint in the same transaction when both live in the same database.
• Handlers are idempotent: upserts keyed by entity ID, or “apply only if event version > stored version”.
• One projection per read need. Projections never read other projections’ tables mid-build; they can depend only on events.
• Failures stop that projection (poison event alert) rather than skipping events silently.

Rebuild without downtime:

1. Create the new read table (order_summary_v2) and a new checkpoint at 0.
2. Run the new projection from position 0 until it catches up with the head.
3. Switch reads (view swap, feature flag, or config) once lag is near zero.
4. Drop the old table after a soak period.

6. Consistency at the edges

Read models lag writes by milliseconds to seconds. Choose per screen:

Technique	When
Return the new state from the command handler (from decided events)	The caller only needs its own result
Return the stream or global position; the read endpoint waits until the projection checkpoint passes it (with a timeout)	Read-your-writes on the next page load
Optimistic UI update on the client	Lists and dashboards
Accept lag and show “updating” states	Analytics and reporting views

7. Versioning, snapshots, personal data

• Never mutate stored events. Evolve with: additive optional fields; upcasters that transform old shapes to the current one on read; a new event type when meaning changes. Keep schemaVersion in metadata and test upcasters against stored samples.
• Snapshots are an optimization: add them only when measured aggregate load time hurts (often several hundred events per stream). Store (streamId, version, state, snapshotSchemaVersion), load the snapshot and then events after it, and treat snapshots as disposable (delete and regenerate when the state shape changes).
• Closing the books: for naturally long-lived entities (accounts), end a stream per period with a summary event and start a new stream seeded from it.
• Personal data: keep PII out of event payloads (reference a separate, deletable store), or encrypt per data subject and delete the key on erasure requests (crypto-shredding). Decide this before the first event is stored.
• Deleting or rewriting streams in production is irreversible; require explicit user confirmation and a backup.

8. Tests

test("cannot cancel a paid order", () => {
  const given: OrderEvent[] = [placed, paymentCaptured];
  const state = given.reduce(evolve, initial);
  expect(() => decideCancel(state, "changed mind")).toThrow("refund required");
});

• Given events, when command, then events (or error). No database needed.
• Concurrency test: two handlers load version 5, both append; exactly one succeeds.
• Rebuild test: rebuild each projection from zero in CI against a fixture event set and compare with the incrementally built tables.

Gotchas

• Event types named after CRUD (Updated) lose the “why” that justified event sourcing.
• Projections that call external services while replaying will re-send emails on rebuild. Side effects belong in separate, checkpointed processors that a rebuild does not touch.
• Querying the event store for business reads (“all orders over 100 EUR”) means a missing projection.
• Large event payloads (documents, images) bloat every replay; store references.

Output contract

## Decision
Justifying requirement(s), bounded context in scope, alternatives rejected
## Events
| Event | Stream | Key fields | Schema version |
## Store and concurrency
Store choice, append contract, global ordering approach
## Projections
| Read model | Events consumed | Checkpoint | Rebuild plan |
## Consistency per screen / endpoint
## Versioning, snapshots, personal data policy