Design and implement event stores for event-sourced systems

Event store design

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

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

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

# Event Store Design

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

Overview

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

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill event-store-design -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/backend-development/skills/event-store-design

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/df73c96fce3b6cd90e88/event-store-design.zip" -OutFile "$env:TEMP\event-store-design.zip"; Expand-Archive "$env:TEMP\event-store-design.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md4.1 KB
references/1 file · 11.2 KB

Read the files here

wshobson/4236bb92 files

SKILL.md4.1 KB

SKILL.md

Show the full text81 lines

event-store-design/SKILL.md81 lines · 4.1 KB

PreviewCode

Outline

RawView on GitHub

Event Store Design

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

1	---
2	name: event-store-design
3	description: Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implementing event persistence patterns.
4	---
5
6	# Event Store Design
7
8	Comprehensive guide to designing event stores for event-sourced applications.
9
10	## When to Use This Skill
11
12	- Designing event sourcing infrastructure
13	- Choosing between event store technologies
14	- Implementing custom event stores
15	- Optimizing event storage and retrieval
16	- Setting up event store schemas
17	- Planning for event store scaling
18
19	## Core Concepts
20
21	### 1. Event Store Architecture
22
23	```
24	┌─────────────────────────────────────────────────────┐
25	│ Event Store │
26	├─────────────────────────────────────────────────────┤
27	│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
28	│ │ Stream 1 │ │ Stream 2 │ │ Stream 3 │ │
29	│ │ (Aggregate) │ │ (Aggregate) │ │ (Aggregate) │ │
30	│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
31	│ │ Event 1 │ │ Event 1 │ │ Event 1 │ │
32	│ │ Event 2 │ │ Event 2 │ │ Event 2 │ │
33	│ │ Event 3 │ │ ... │ │ Event 3 │ │
34	│ │ ... │ │ │ │ Event 4 │ │
35	│ └─────────────┘ └─────────────┘ └─────────────┘ │
36	├─────────────────────────────────────────────────────┤
37	│ Global Position: 1 → 2 → 3 → 4 → 5 → 6 → ... │
38	└─────────────────────────────────────────────────────┘
39	```
40
41	### 2. Event Store Requirements
42
43	\| Requirement \| Description \|
44	\| ----------------- \| ---------------------------------- \|
45	\| Append-only \| Events are immutable, only appends \|
46	\| Ordered \| Per-stream and global ordering \|
47	\| Versioned \| Optimistic concurrency control \|
48	\| Subscriptions \| Real-time event notifications \|
49	\| Idempotent \| Handle duplicate writes safely \|
50
51	## Technology Comparison
52
53	\| Technology \| Best For \| Limitations \|
54	\| ---------------- \| ------------------------- \| -------------------------------- \|
55	\| EventStoreDB \| Pure event sourcing \| Single-purpose \|
56	\| PostgreSQL \| Existing Postgres stack \| Manual implementation \|
57	\| Kafka \| High-throughput streaming \| Not ideal for per-stream queries \|
58	\| DynamoDB \| Serverless, AWS-native \| Query limitations \|
59	\| Marten \| .NET ecosystems \| .NET specific \|
60
61	## Templates and detailed worked examples
62
63	Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
64
65	## Best Practices
66
67	### Do's
68
69	- Use stream IDs that include aggregate type - `Order-{uuid}`
70	- Include correlation/causation IDs - For tracing
71	- Version events from day one - Plan for schema evolution
72	- Implement idempotency - Use event IDs for deduplication
73	- Index appropriately - For your query patterns
74
75	### Don'ts
76
77	- Don't update or delete events - They're immutable facts
78	- Don't store large payloads - Keep events small
79	- Don't skip optimistic concurrency - Prevents data corruption
80	- Don't ignore backpressure - Handle slow consumers
81