Home
cd ../playbooks
Developer ToolsAdvanced

Event Store Design

Design and implement an event store for an event-sourced system — the append-only, per-stream-ordered, globally-positioned model; a technology comparison (EventStoreDB, PostgreSQL, Kafka, DynamoDB, Marten); a complete PostgreSQL schema with the UNIQUE(stream_id, version) constraint that enforces optimistic concurrency; and the snapshot, subscription, and idempotency patterns that keep it correct.

15 minutes
By rmyndharisSource
#event-sourcing#cqrs#postgresql#architecture#distributed-systems#database-design

The difference between an event store and a table you append rows to is one UNIQUE(stream_id, version) constraint — without it, two concurrent writers silently corrupt an aggregate's history, and with it, a conflicting write fails loudly and forces a re-read, which is the entire correctness guarantee event sourcing depends on.

Who it's for: backend engineers building event-sourced or CQRS systems, architects choosing an event store technology, developers implementing event persistence on PostgreSQL or DynamoDB, teams adding audit-grade immutable event logs who need the concurrency and snapshotting patterns done right

Example

"We want to add event sourcing on our existing Postgres stack" → A complete events/snapshots/subscription_checkpoints schema with per-stream and global ordering, the UNIQUE(stream_id, version) optimistic-concurrency constraint explained, an immutable Event record and the append/read-stream/read-all/subscribe operations, plus snapshotting so aggregate replay doesn't start from event 1 every time

CLAUDE.md Template

New here? 3-minute setup guide → | Already set up? Copy the template below.

Or install from your terminal:
npx ccplaybooks add event-store-design
# Event Store Design

Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing an event store technology, or implementing event persistence patterns.

## Core Concepts

An event store holds one append-only, ordered stream per aggregate, plus a global position across all streams:

```
Event Store
  Stream 1 (Aggregate)   Stream 2 (Aggregate)   Stream 3 (Aggregate)
    Event 1                Event 1                Event 1

Get new playbooks like this one

One email a week with new Claude Code workflows. Free, like everything here.

No spam. Unsubscribe anytime.

README.md

What This Does

A design-and-implementation guide for the event store at the heart of an event-sourced system. It starts from the model that makes event sourcing work — one append-only, immutable, per-aggregate stream with both per-stream and global ordering — and the five requirements any real event store has to meet (append-only, ordered, versioned, subscribable, idempotent). A technology comparison table lays out when EventStoreDB, PostgreSQL, Kafka, DynamoDB, or Marten is the right backend and what each gives up.

The core of the playbook is a complete, correct PostgreSQL implementation: an events table with a global_position sequence and the UNIQUE(stream_id, version) constraint that enforces optimistic concurrency (a conflicting concurrent write fails and forces a re-read rather than corrupting the stream), plus snapshots and subscription_checkpoints tables and the indexes each query pattern needs. It pairs that with an immutable Event record, the four core operations (append with expected-version, read-stream for replay, read-all for projections, subscribe for live consumers), snapshotting to bound replay cost, and the DynamoDB conditional-write equivalent — then closes with the do's and don'ts that keep an event log trustworthy (never mutate events, keep payloads small, never skip optimistic concurrency, include correlation/causation IDs for tracing).


Quick Start

Step 1: Create a Project Folder

mkdir event-store && cd event-store

Step 2: Download the Template

Click Download above, then:

mv ~/Downloads/CLAUDE.md ./

Step 3: Design Your Event Store

claude

Tell Claude your stack and aggregate model. It will pick a backend, generate the schema (with the optimistic-concurrency constraint wired in), and implement the append/read/subscribe operations plus snapshotting for your aggregates.


Tips & Best Practices

  • Treat the UNIQUE(stream_id, version) constraint as non-negotiable — it is the entire optimistic-concurrency mechanism; dropping it to "simplify" the schema reintroduces the silent stream-corruption bug event sourcing exists to prevent.
  • Version your events from day one and keep correlation/causation IDs in metadata — both are nearly impossible to retrofit cleanly once you have production history, and both are what make schema evolution and cross-service tracing tractable later.
  • Snapshot long streams so aggregate reconstruction doesn't replay from event 1 on every load — but keep snapshots as a derived optimization, never the source of truth.

Limitations

  • This is the persistence layer only — projections/read models, command handling, and schema/upcasting strategies for evolving event shapes are adjacent concerns the playbook points at but doesn't fully implement.
  • The PostgreSQL schema is a solid general-purpose starting point, not a tuned high-throughput configuration; very high write volumes may need partitioning, archival tiers, or a purpose-built store like EventStoreDB or Kafka.
  • Event sourcing is a significant architectural commitment with real operational cost — this playbook assumes that decision is already made and doesn't argue whether a given system should be event-sourced at all.

$Related Playbooks

Developer Tools

Ginkgo Table and Dynamic Specs

Parameterize and generate Ginkgo test specs correctly — DescribeTable/Entry, the four ways to name an entry, DescribeTableSubtree for multi-It rows, reusable entry sets, and the one gotcha (Entry params evaluate at construction time, not BeforeEach time) that causes most table-spec bugs.

5 minutes
Intermediate
Developer Tools

Ginkgo Timeouts and Async Testing

Make Ginkgo specs interruptible and test asynchronous behavior correctly — SpecContext cancellation, NodeTimeout/SpecTimeout/GracePeriod, Eventually/Consistently with proper context propagation, and the two goroutine rules (GinkgoRecover, poll-don't-block) that prevent one failed assertion from crashing an entire Go test suite.

5 minutes
Intermediate
Developer Tools

Writing Ginkgo Specs

Author correct Ginkgo specs — container vs. subject vs. setup nodes, the declare-in-container/initialize-in-setup rule that prevents the most common Ginkgo bug, JustBeforeEach for separating creation from configuration, DeferCleanup for restore-not-clear teardown, and GinkgoHelper() for failure locations that point at the caller instead of the helper.

5 minutes
Beginner
Developer Tools

Git Conflict Resolution Framework

A plan-first framework for resolving Git merge conflicts by combining both branches' intent instead of blindly picking a side — categorized resolution patterns for imports, tests, generated files, configs, code logic, and struct definitions, with a mandatory approval step before any file is touched.

5 minutes
Intermediate
Developer Tools

Building Animations in Expo and React Native

A construction discipline for React Native motion: a frequency gate that produces zero lines of code when nothing should animate, a cheapest-tool-that-fits selection table, spring/easing values instead of guesses, and the JS-thread rules that separate 60fps from 20fps on a real device.

10 minutes
Advanced
Developer Tools

Explanatory Coding Mode

Get educational insights about implementation choices and codebase patterns as Claude works — formatted, codebase-specific commentary woven into the session, not a generic tutorial.

2 minutes
Beginner
Developer Tools

7-Phase Feature Development Workflow

Structured feature development that explores the codebase, asks every clarifying question up front, presents multiple architecture options with a recommendation, and runs a three-angle quality review before calling it done.

5 minutes
Intermediate
Developer Tools

Git Commit & PR Automation

Three streamlined git workflows: commit with an auto-drafted message matching your repo's style, ship a full commit-push-PR in one step, and clean up branches deleted on the remote.

5 minutes
Beginner
Developer Tools

Hookify Guardrails

Create custom Claude Code guardrails with lightweight markdown rule files instead of hand-editing hooks.json — pattern matching, no restart required, rules live-load on the next tool call.

5 minutes
Beginner
Developer Tools

GEO Schema: Structured Data for AI Citation

Audit and generate schema.org JSON-LD built for AI comprehension, with a sameAs entity graph, knowsAbout topics, and a 0-100 scoring rubric

10 minutes
Intermediate
Developer Tools

GEO Technical SEO Audit: 8 Categories, 100 Points

A scored technical audit covering crawlability, indexability, security, Core Web Vitals, and the server-side rendering check that decides whether AI crawlers see your content at all

15 minutes
Advanced
Developer Tools

GEO Toolkit Updater

Pull the latest geo-seo-claude skills, agents, scripts, and schema templates from upstream, with a diff summary before anything is overwritten

5 minutes
Beginner

Browse all Developer Tools playbooks →