Event Sourcing Rules

event-sourcingarchitecturepatterns

Conventions for implementing event sourcing where system state is derived from an immutable, append-only log of domain events rather than mutable records.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Event Sourcing Rules ## Event Design - Events represent facts that have already happened — name them in past tense: `OrderPlaced`, `PaymentProcessed`, `AccountClosed`. - Events are immutable value objects. Once written to the store, an event must never be modified or deleted. - Include a schema version in every event type: `{ type: "OrderPlaced", version: 1, ... }`. - Events must carry all data needed to reconstruct state — never store references that require external lookups during replay. - Keep events fine-grained: one fact per event. Prefer `ItemAddedToCart` + `ItemRemovedFromCart` over `CartUpdated`. ## Event Schema & Versioning - Maintain backward compatibility: add optional fields only; never remove or rename existing fields. - Use upcasters to transform old event versions to the current schema during replay. - Document every schema change in a migration log. Treat breaking changes as new event types. - Include metadata on every event: `eventId` (UUID), `aggregateId`, `aggregateType`, `occurredAt` (UTC ISO-8601), `causationId`, `correlationId`. ## Aggregate Rules - Aggregates must never directly mutate internal state — all mutations happen in `apply(event)` methods. - The `apply(event)` method must be pure and deterministic: same events → same state, always. - Command methods validate preconditions, then emit events. They never mutate state directly. - Load aggregates by replaying their full event stream from the event store. - Implement snapshots for aggregates with high event counts (> 200 events) to speed up rehydration. ## Event Store - The event store is append-only. Provide `append(events, expectedVersion)` with optimistic concurrency control. - Use optimistic locking: pass the expected stream version when appending; throw `ConcurrencyException` on conflict. - Expose `load(aggregateId, fromVersion?)` to retrieve event streams. - Persist events atomically within a transaction per aggregate. - Use an outbox pattern to reliably publish events to message brokers after successful persistence. ## Projections & Read Models - Build projections by subscribing to the event stream and maintaining a separate read-optimized store. - Projections must be idempotent: handle duplicate events gracefully (track last processed event position). - Support full rebuild: projections must be rebuildable by replaying the entire event log from position 0. - Separate projection state from event store — use different databases/tables optimized for each purpose. ## Anti-Patterns - Do not store snapshots in the event stream — keep them in a separate snapshot store. - Do not use events for infrastructure concerns (logging, metrics) — only domain facts belong in the event store. - Do not load entire event histories in projections without checkpointing — track the last processed offset. - Do not share event schemas across bounded contexts — translate at context boundaries. - Do not delete events to "fix" bugs — publish corrective events instead. ## Testing - Use a "given/when/then" style: given prior events, when command applied, then new events are emitted. - Test aggregate rehydration: serialize events, replay them, assert state matches. - Test upcasters explicitly with old event payloads. - Use an in-memory event store for unit tests; use a real store (EventStoreDB, Postgres) for integration tests.

CLI

npx mindaxis apply event-sourcing-rules --target cursor --scope project

Используется в паках

Event-Driven Design

Scalable async event-driven systems

Открыть пак →

Hexagonal Architecture

DDD, CQRS, and ports & adapters patterns

Открыть пак →

← Правила

Event Sourcing Rules

event-sourcingarchitecturepatterns

Conventions for implementing event sourcing where system state is derived from an immutable, append-only log of domain events rather than mutable records.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

CLI

npx mindaxis apply event-sourcing-rules --target cursor --scope project

Используется в паках

Event-Driven Design

Scalable async event-driven systems

Открыть пак →

Hexagonal Architecture

DDD, CQRS, and ports & adapters patterns

Открыть пак →