event-store-design
wshobson/agents
Design and implement event stores for event-sourced systems with architecture patterns and technology guidance.
What is event-store-design?
This skill provides comprehensive guidance for designing event stores in event-sourced applications. Use it when building event sourcing infrastructure, selecting event store technologies, implementing custom event stores, or optimizing event persistence and retrieval patterns.
- Compare event store technologies (EventStoreDB, PostgreSQL, Kafka, DynamoDB, Marten) with trade-offs
- Design event store architecture with streams, aggregates, and global ordering
- Implement append-only, versioned event storage with optimistic concurrency control
- Plan event subscriptions and real-time notification systems
- Apply best practices for stream IDs, correlation tracking, and idempotency
- Optimize indexing and query patterns for event retrieval
How to install event-store-design
npx skills add https://github.com/wshobson/agents --skill event-store-designHow to use event-store-design
- 1.Review the event store architecture diagram to understand streams, aggregates, and global ordering
- 2.Consult the technology comparison table to select the right event store for your constraints
- 3.Apply the Do's best practices: use typed stream IDs, include correlation IDs, version events, implement idempotency
- 4.Avoid the Don'ts: never update/delete events, keep payloads small, enforce optimistic concurrency, handle backpressure
- 5.Reference the detailed templates in references/details.md for concrete implementation examples
Use cases
- Choosing between EventStoreDB, PostgreSQL, or Kafka for a new event-sourced system
- Designing stream structure and event schema for order or user aggregates
- Implementing idempotent event writes to handle duplicate requests safely
- Setting up event subscriptions for downstream projections or sagas
- Planning event store scaling and handling high-throughput streaming scenarios
- Backend engineers building event-sourced systems
- Architects designing CQRS and event sourcing infrastructure
- Teams migrating to event sourcing from traditional databases
- Developers optimizing event storage and retrieval performance
event-store-design FAQ
Stream ordering maintains event sequence within a single aggregate stream (e.g., Order-123). Global ordering tracks all events across the entire event store for subscriptions and projections.
They enable tracing causal relationships between events across aggregates and systems, essential for debugging distributed systems and understanding event chains.
Implement idempotency using event IDs for deduplication. When the same event ID is written twice, the store rejects or ignores the duplicate rather than creating a duplicate entry.
No. Keep events small and focused on facts. Store large payloads separately and reference them by ID, reducing storage overhead and improving query performance.
It uses version numbers to detect conflicts: writes include the expected version, and the store rejects writes if the stream version has advanced, preventing lost updates.
Full instructions (SKILL.md)
Source of truth, from wshobson/agents.
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
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
Related skills
More from wshobson/agents and the wider catalog.
fastapi-templates
Production-ready FastAPI project templates with async patterns, dependency injection, and error handling.
file-conversion
Convert files between 999 formats (PDF, images, video, audio, documents, data) via free ChangeThisFile service.
finetuning-method-selection
Route fine-tuning decisions: whether to fine-tune at all, and which method (SFT, DPO/ORPO/KTO, GRPO/RLVR, CPT) fits your data.
gdpr-data-handling
Implement GDPR-compliant data handling with consent management and data subject rights.
git-advanced-workflows
Master rebasing, cherry-picking, bisect, worktrees, and reflog for clean Git history and recovery.
github-actions-templates
Production-ready GitHub Actions workflow templates for CI/CD, testing, building, and deployment.