Event Sourcing and CQRS Design: [Bounded context or service name]

Design document for a service that stores state as a sequence of domain events (event sourcing) and separates the write model from read models (Command Query Responsibility Segregation, CQRS): when to use it, aggregates and the event catalogue, event schema and versioning, the event store, projections, consistency and ordering, snapshots, replay, idempotency, GDPR erasure and the main interaction flow. Based on common industry practice. Replace every [bracketed] value and every row marked Example; the examples follow a shopping cart and order context.

1. When to use and decision

Decision: [Use event sourcing with CQRS / Use CQRS only / Do not use]. Recorded in [ADR-NNN].

Avoid this pattern for: [list]. Example: reference data such as the product catalogue and user preferences, which stay CRUD.

2. Aggregates and event catalogue

2.1 Aggregates

2.2 Event catalogue

Naming rules: past tense, domain language, no technical verbs such as "Updated" for a whole aggregate.

3. Event schema and versioning

Every event is stored with a common envelope:

{
  "event_id": "0f8b6c1e-4a1d-4a63-9a7e-2b1f7f0c9d21",
  "stream_id": "cart-6c2a",
  "stream_version": 7,
  "event_type": "ItemAddedToCart",
  "schema_version": 2,
  "occurred_at": "2026-10-21T09:14:03.120Z",
  "correlation_id": "req-91a2",
  "causation_id": "cmd-55f0",
  "tenant_id": "t-001",
  "payload": { "sku": "SKU-1042", "quantity": 2, "unit_price": { "amount": "19.90", "currency": "EUR" } }
}

Upcasting: when an old event is read, a chain of upcasters converts it step by step to the current version before it reaches the aggregate or a projection. Example: ItemAddedToCart v1 stored price as a number in cents; the v1 to v2 upcaster converts it to unit_price with amount and currency taken from CartCreated.

4. Event store

5. Projections and read models

Each projection records its checkpoint (global_position last processed) in the same transaction as its writes, so restarts resume exactly where they stopped.

6. Consistency and ordering

• Within an aggregate: strongly consistent. Commands load the stream, check invariants and append with optimistic concurrency.
• Across aggregates: eventually consistent, coordinated by process managers (sagas) reacting to events. Example: CartCheckedOut triggers the order process manager to issue PlaceOrder.
• Read models: eventually consistent. Commands return the new stream version; the UI can wait until the read model reaches that version ("read your own writes") for order confirmation.
• Ordering: guaranteed per stream by stream_version. Across streams only global_position order is guaranteed in the store; the broker partitions by stream_id so per-aggregate order is preserved for consumers.

7. Snapshots, replay and rebuild

8. Idempotency

9. GDPR erasure and personal data

10. Main interaction flow

The sequence shows a customer adding an item to a cart and the cart view being updated.

11. Operations and testing

Standard and licence note

Based on common industry practice for event sourcing and CQRS, as described in public writing by Greg Young, Martin Fowler and others. Original text written for this collection; examples are illustrative. The GDPR section describes a technical pattern and is not legal advice. Template licence: MIT.