Event Store Design

From the author

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

— the description by Seth Hobson

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to designing event stores, covering core architectural requirements, technology comparisons, and implementation best practices. It emphasizes the immutable, append-only nature of event sourcing and provides concrete templates for schema design and application-level implementation to ensure data integrity, concurrency control, and efficient event retrieval.

What it does

Defines core requirements for event stores including immutability and optimistic concurrency.
Compares common storage technologies like PostgreSQL, Kafka, and DynamoDB for event sourcing.
Provides SQL schema templates for event and snapshot storage.
Offers implementation patterns for appending events with version checking.
Outlines best practices for stream naming, event metadata, and schema evolution.
Details strategies for handling idempotency and subscription checkpoints.

When to use it

When architecting the persistence layer for an event-sourced system.
When evaluating which database technology best fits your event sourcing needs.
When implementing custom event store logic in a backend application.
When optimizing event storage schemas for performance and scalability.
When establishing patterns for event versioning and schema evolution.

Advantages

Ensures data consistency through optimistic concurrency control.
Provides a clear framework for choosing the right storage technology.
Includes ready-to-use SQL and code templates for rapid implementation.
Promotes best practices for long-term system maintainability and tracing.
Addresses critical operational concerns like idempotency and backpressure.

Usage examples

“How should I structure my PostgreSQL schema for an event store?”: The agent provides a SQL template including tables for events, snapshots, and subscription checkpoints with appropriate indexing.
“What are the pros and cons of using Kafka versus PostgreSQL for event sourcing?”: The agent compares the two, highlighting Kafka's high-throughput streaming capabilities versus PostgreSQL's suitability for per-stream queries.
“How do I implement optimistic concurrency when appending events?”: The agent explains the version-checking pattern and provides a Python code example using a database transaction.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/wshobson/event-store-design/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip event-store-design.zip -d .agents/skills

Documentation by Seth Hobson

Comprehensive guide to designing event stores for event-sourced applications.

When to Use This Skill

Designing event sourcing infrastructure
Choosing between event store technologies
Implementing custom event stores
Optimizing event storage and retrieval
Setting up event store schemas
Planning for event store scaling

Core Concepts

1. Event Store Architecture

┌─────────────────────────────────────────────────────┐
│                    Event Store                       │
├─────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
│  │   Stream 1   │  │   Stream 2   │  │   Stream 3   │ │
│  │ (Aggregate)  │  │ (Aggregate)  │  │ (Aggregate)  │ │
│  ├─────────────┤  ├─────────────┤  ├─────────────┤ │
│  │ Event 1     │  │ Event 1     │  │ Event 1     │ │
│  │ Event 2     │  │ Event 2     │  │ Event 2     │ │
│  │ Event 3     │  │ ...         │  │ Event 3     │ │
│  │ ...         │  │             │  │ Event 4     │ │
│  └─────────────┘  └─────────────┘  └─────────────┘ │
├─────────────────────────────────────────────────────┤
│  Global Position: 1 → 2 → 3 → 4 → 5 → 6 → ...     │
└─────────────────────────────────────────────────────┘

2. Event Store Requirements

Requirement	Description
Append-only	Events are immutable, only appends
Ordered	Per-stream and global ordering
Versioned	Optimistic concurrency control
Subscriptions	Real-time event notifications
Idempotent	Handle duplicate writes safely

Technology Comparison

Technology	Best For	Limitations
EventStoreDB	Pure event sourcing	Single-purpose
PostgreSQL	Existing Postgres stack	Manual implementation
Kafka	High-throughput streaming	Not ideal for per-stream queries
DynamoDB	Serverless, AWS-native	Query limitations
Marten	.NET ecosystems	.NET specific

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Use stream IDs that include aggregate type - Order-{uuid}
Include correlation/causation IDs - For tracing
Version events from day one - Plan for schema evolution
Implement idempotency - Use event IDs for deduplication
Index appropriately - For your query patterns

Don'ts

Don't update or delete events - They're immutable facts
Don't store large payloads - Keep events small
Don't skip optimistic concurrency - Prevents data corruption
Don't ignore backpressure - Handle slow consumers

Files

ATTRIBUTION.mdAdded by AutoGineer992 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md4.1 KiB
references/details.md11.2 KiB

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Setup TS Deep Modules
Matt Pocock· Community
Configures dependency-cruiser to enforce deep module boundaries in TypeScript repositories.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITLow riskHas scriptsGitHub stars of the source repository317.5k
To Spec
Matt Pocock· Community
Synthesizes conversation context into a structured technical specification and publishes it to a project issue tracker.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Improve Codebase Architecture
Matt Pocock· Community
A systematic process to identify, visualize, and refine architectural deepening opportunities in a codebase.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Domain Modeling
Matt Pocock· Community
An expert assistant for defining project terminology, maintaining a glossary, and documenting architectural decisions.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Codebase Design
Matt Pocock· Community
A shared vocabulary and set of principles for designing deep, testable, and maintainable software modules.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k
Prototype
Matt Pocock· Community
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
Software developmentClaude CodeClaude appsOpenAI Codex+14 more
MITGitHub stars of the source repository317.5k

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download event-store-design.zip