arch-event-sourcing

One-line summary

Persist the sequence of state-changing events as the source of truth. Current state is derived by replaying events. The event log is append-only, immutable, and authoritative.

When to use this skill

• Audit / regulatory requirements that demand a complete history of changes.
• Business that genuinely thinks in terms of "what happened" (banking transactions, claim adjustments, supply-chain events).
• Need to answer temporal queries ("what was the state on date X").
• Multiple projections of the same data needed and easier to materialize from events than to maintain by hand.
• Pairs naturally with CQRS (see arch-cqrs) when reads need different shapes than the canonical event stream.

When NOT to use this skill

• The domain doesn't think in events — forcing the model into event shape is more cost than benefit.
• Current state is sufficient and history is rarely queried — CRUD is simpler.
• Team unfamiliar with eventual consistency, replay semantics, or event versioning — operational pain is severe.
• "Event sourcing" because microservices are trendy and we read about it somewhere — that's not a reason.

Core content

The event store. An append-only log of events, each tagged with an aggregate ID, a sequence number, and a timestamp. Writing is an append(events); reading for a specific aggregate is eventsFor(aggregateId).

Rebuilding state. An aggregate's current state is the fold over its events:

state = events.fold(initial) { acc, event -> apply(acc, event) }

To handle a new command: load the events, replay to get the current state, run the command, append new events. The state in memory is transient; the events on disk are the truth.

Snapshots. For long-lived aggregates (years of events), replaying from the start gets slow. A snapshot is a periodic save of state-at-event-N. Loading uses the snapshot plus events after N. Snapshots are an optimization, not the source of truth — the events still are.

Event versioning. Events live forever. Their schemas must evolve forward-compatibly. Tactics:

• Additive changes only — new fields are optional, never required.
• Upcasters — code that transforms old event versions into the current shape on read.
• Weak schema (JSON with permissive parsing) — flexibility at the cost of compile-time safety.

CQRS pairing. Event-sourced writes naturally produce events that project into read models. Most production event-sourced systems use CQRS for queries because the event stream is awkward to query directly.

Operational considerations.

• Event store availability is critical — it's the source of truth.
• Tools (replay, projection rebuild, schema migration) need to exist before you commit; building them mid-project is painful.
• Storage grows monotonically. Plan for it.
• Aggregates with millions of events without snapshots will struggle.

Decision heuristics

• Event-source aggregates where audit / temporal queries / multiple projections are genuinely required. Don't blanket-apply.
• Snapshot interval is a tuning knob — start with 100-500 events; adjust based on replay performance.
• Treat event schemas as a public API — version them; never break them.
• Build the operational toolkit (replay, rebuild, migrate) before you depend on event sourcing in production.

Anti-patterns

• Event-sourcing the whole system reflexively. Most subdomains don't need it. Apply selectively — typically only the core domain with strong audit needs.
• Mutable events. Editing past events to "fix" history. Defeats the entire pattern. To "correct", append a compensating event.
• Events as DTOs. Events with no semantic meaning beyond "fields changed". Should be domain events: past-tense, business-meaningful.
• Replaying without snapshots on hot aggregates. Every command takes seconds to seconds-many.
• Schema breakage without upcasters. Old events become unreadable. The history is lost in practice.

See also

• arch-cqrs — read models from event projections.
• arch-event-driven — events as cross-context communication (often the same events).
• ddd-domain-event — the tactical-level event concept.
• ddd-aggregate — event-sourced aggregates produce events as part of command handling.

References

• Khononov, Learning DDD, Ch. 7 (Event-Sourced Domain Model).
• Vaughn Vernon, Implementing Domain-Driven Design — Ch. 8 has the canonical Java treatment.
• Greg Young, talks and essays on event sourcing (foundational).