DEV Community: Grady Zhuo

Understanding DDD Aggregates Through Board Games and Battlefields

Grady Zhuo — Thu, 26 Mar 2026 08:10:47 +0000

I've been learning DDD for almost two years now. My understanding of Aggregate kept evolving — from accidentally treating it as just a Write Model, to roughly grasping that "an Aggregate protects invariants." But something always felt unclear. Then a couple days ago, while explaining it to a teammate, I tried using a game analogy, and suddenly everything clicked.

An Aggregate Is a Board Game

Think of a board game. One game is one Aggregate. It has characters, items, and events — but most importantly, it has rules. Every action taken inside that game must follow those rules. The rules of Catan only apply in Catan. You can't bring Monopoly's "collect $200 when passing Go" rule into it.

Catan itself is the Aggregate — not the characters, not the items, but the game as a whole. Once you have those characters and items living inside the Aggregate, you can design Commands to operate on them. So an Aggregate protecting its invariants is really just like a board game enforcing its rules. The only difference is that in the real world, those rules are called business rules. And in the real world, there's no escaping them.

Within a single turn, every action must be resolved at once — you can't do half a move and come back later. This maps to another core concept:

An Aggregate is a Transactional Consistency Boundary. Either everything succeeds, or everything fails. No in-between.

The Battlefield vs. The War Room

Later, while discussing with another teammate, I needed to explain how the same entity can exist across two different Aggregates. I found that a war room sand table analogy works surprisingly well.

The real battlefield is one Aggregate. The commander's sand table is another. On the sand table, flags represent each general — but the flag is not the general. It's just an identifier (an ID) that tells the commander "this person exists." The general's full state lives on the battlefield.

The two Aggregates have completely different concerns about the same person. The sand table doesn't need to know how badly the general is wounded or how many troops he has left. It only needs to know: "is he still available?"

That's why across Aggregate boundaries, you only store an ID — never an object reference. Boundaries must stay clear.

When something happens on the battlefield, a messenger rides to the war room and the commanders update the sand table. That messenger is what DDD calls a Policy. It listens to a Domain Event fired by one Aggregate, then decides whether to trigger a reaction in another.

This is exactly why DDD pairs so naturally with EventSourcing and CQRS — the entire system collaborates through events flowing between boundaries. Not direct calls. Not shared objects. Events.

Wrapping Up

Once these two things clicked, a lot of design decisions that used to feel stuck suddenly had clear answers.

I'm not sure these analogies will work for everyone, but for me, they were the first time DDD stopped feeling like a pile of jargon. Sometimes you're not stuck because you're not trying hard enough — you just haven't found the right angle yet.

If you've had a similar moment of clarity, I'd love to hear about it in the comments.

swift-kurrentdb 2.0.0 — Event Sourcing for Swift, Rebuilt from the Ground Up

Grady Zhuo — Sun, 15 Mar 2026 09:43:54 +0000

I'm excited to announce swift-kurrentdb 2.0.0 — a complete redesign of the Swift client for KurrentDB (formerly EventStoreDB).

If you're building Event Sourcing systems with Server-Side Swift, this release is for you.

Background

KurrentDB is a purpose-built event store for Event Sourcing. It stores events as an append-only log, supports projections, persistent subscriptions, and cluster deployments with leader election.

swift-kurrentdb is the community Swift client for it, built on top of grpc-swift 2.x and Swift Concurrency.

Version 1.x worked, but it wasn't designed with Swift 6's strict concurrency model in mind. Rather than patch it, 2.0 is a ground-up redesign that feels native to modern Swift.

What changed in 2.0

Target-based hierarchical API

The biggest change is how you interact with the client. The old flat-method style is replaced by a composable, target-based design:

// 1.x — flat methods on the client
try await client.appendToStream("orders", events: [event]) {
    $0.revision(expected: .any)
}

// 2.x — select a target, then call the operation
try await client.streams(of: .specified("orders"))
    .append(events: [event]) {
        $0.expectedRevision = .any
    }

The same pattern applies everywhere:

// Streams
client.streams(of: .specified("orders"))
client.streams(of: .all)

// Projections
client.projections(name: "order-count")
client.projections(system: .byCategory)

// Persistent Subscriptions
client.persistentSubscriptions(stream: "orders", group: "workers")

This makes the API more discoverable, consistent, and easier to extend.

Swift 6 strict concurrency — zero data races

KurrentDBClient is an actor. All public operations are async. The entire codebase compiles cleanly under -strict-concurrency=complete — no @unchecked Sendable shortcuts, no suppression pragmas.

Typed throws

Every operation throws KurrentError — not any Error. You always know exactly what can go wrong:

do {
    try await client.streams(of: .specified("orders"))
        .append(events: [event]) {
            $0.expectedRevision = .streamExists
        }
} catch KurrentError.wrongExpectedVersion {
    // optimistic concurrency conflict — handle gracefully
} catch KurrentError.streamNotFound {
    // stream doesn't exist yet
}

No more as? SomeError casting in catch blocks.

Cluster resilience

2.0 adds automatic node re-discovery when a cluster node fails. The client:

Detects the failure via gRPC status codes
Invalidates the cached node
Re-runs gossip-based discovery to find a healthy node
Retries the operation transparently

Retry policy and node cache TTL are now fully configurable:

let settings = ClientSettings.localhost()
    .retryPolicy(.init(maxAttempts: 5, interval: .seconds(2)))
    .nodeCacheTTL(.seconds(30))

Subscription dropped events

Persistent subscriptions now surface a subscriptionDropped error with lastRevision and lastPosition — the exact checkpoint to resume from after an unexpected disconnect:

do {
    for try await result in subscription.events {
        try await subscription.ack(readEvents: result.event)
    }
} catch KurrentError.subscriptionDropped(let reason, let lastRevision, _) {
    // resume from lastRevision on reconnect
}

Migrating from 1.x

I know breaking changes are painful. That's why 2.0 ships a KurrentDB_V1 compatibility library in the same package.

Switch your dependency target:

// Package.swift
.product(name: "KurrentDB_V1", package: "swift-kurrentdb")

Change your import:

import KurrentDB_V1   // was: import KurrentDB

That's it. Your existing 1.x code compiles and runs unchanged. All 1.x methods are marked @deprecated, so Xcode guides you through the migration at your own pace — no big-bang rewrites required.

👉 Full Migration Guide

Quality & compatibility


Tests	174 across 11 suites
Coverage	75% line coverage
Test environment	Live 3-node TLS KurrentDB cluster
Server support	KurrentDB 25.1, 26.0 · EventStoreDB 24.x
Swift versions	6.0, 6.1, 6.2
Platforms	macOS 15+ · iOS 18+ · Linux

Test suites cover streams (append, read, subscribe, optimistic concurrency), projections, persistent subscriptions (ACK/NACK, park, replay), users, operations, gossip, and monitoring — all running against a real cluster, not mocks.

Get started

// Package.swift
.package(url: "<https://github.com/gradyzhuo/swift-kurrentdb.git>", from: "2.0.0")

import KurrentDB

let client = KurrentDBClient(
    settings: .localhost()
        .authenticated(.credentials(username: "admin", password: "changeit"))
)

// Append an event
let event = EventData(eventType: "OrderPlaced", model: Order(id: "123", total: 99.99))
try await client.streams(of: .specified("orders")).append(events: [event])

// Read events
let stream = try await client.streams(of: .specified("orders")).read {
    $0.startFrom(revision: .start).limit(10)
}
for try await response in stream {
    print(try response.event?.record.eventType ?? "checkpoint")
}

Links

Feedback, issues, and PRs are very welcome. Event Sourcing in the Swift ecosystem is still young — let's build it together.

Introducing KurrentDB-Swift: Bringing Event Sourcing to Server-Side Swift

Grady Zhuo — Sun, 16 Nov 2025 15:56:50 +0000

Event Sourcing is transforming how we build modern applications. Companies like Uber, Netflix, and Amazon use it to build scalable, auditable systems. But if you're a Swift developer wanting to leverage this powerful pattern, you've been out of luck—until now.

Today, I'm excited to share KurrentDB-Swift, a production-ready Swift client for Kurrent (formerly EventStoreDB) that brings enterprise-grade Event Sourcing capabilities to the Swift ecosystem.

📊 Quick Stats

Before we dive in, here's what KurrentDB-Swift brings to the table:

⏱️ Over 1 year of active development
💪 425+ commits across 46 releases
📦 Available on Swift Package Index
✅ Zero data-race safety (Swift 6 ready)
📚 Comprehensive documentation with tutorials
🔧 Actively maintained (last update: 3 days ago)

💡 Why This Matters

The Problem

Server-Side Swift is maturing rapidly. We have Vapor, Hummingbird, and excellent tools for building web services. But when it comes to Event Sourcing—a critical pattern for building complex, scalable systems—Swift developers have been left behind.

Kurrent (the company behind EventStoreDB) provides official clients for .NET, Java, Node.js, Go, and Rust. But Swift? Nothing.

The Solution

KurrentDB-Swift fills this gap. It's not just a wrapper—it's a ground-up implementation designed to feel natural in Swift, leveraging modern concurrency, type safety, and the language features Swift developers expect.

🎓 What is Event Sourcing?

If you're new to Event Sourcing, here's a quick primer.

Traditional Approach: Store Current State

// Database stores only the current state
struct BankAccount {
    var balance: Decimal = 100.00
}

// We lose the history
account.balance += 50  // balance is now 150
account.balance -= 30  // balance is now 120
// How did we get here? We don't know!

Event Sourcing: Store All Events

// Database stores every event that happened
enum AccountEvent {
    case opened(initialBalance: Decimal)
    case deposited(amount: Decimal)
    case withdrawn(amount: Decimal)
}

// Complete audit trail
let events = [
    .opened(initialBalance: 100),
    .deposited(amount: 50),   // balance: 150
    .withdrawn(amount: 30)    // balance: 120
]

// We can see EXACTLY what happened, when, and why

Benefits

✅ Complete audit trail - Know exactly what happened
✅ Time travel - See state at any point in history
✅ Event-driven architecture - React to changes in real-time
✅ Easy debugging - Replay events to reproduce issues
✅ Business insights - Analyze patterns and behaviors

🚀 Show, Don't Tell: A Real Example

Let's build a simple order system to see KurrentDB-Swift in action.

Define Your Events

import KurrentDB

// Domain events as Swift types
enum OrderEvent: Codable {
    case created(customerId: String, items: [Item])
    case paid(amount: Decimal, method: String)
    case shipped(trackingNumber: String)
    case delivered(timestamp: Date)
}

struct Item: Codable {
    let productId: String
    let quantity: Int
    let price: Decimal
}

Write Events

// Connect to Kurrent
let client = KurrentDBClient(settings: .localhost())

// Create events
let orderId = UUID().uuidString
let streamName = "order-\(orderId)"

let events = [
    EventData(
        eventType: "OrderCreated",
        model: OrderEvent.created(
            customerId: "customer-123",
            items: [Item(productId: "prod-456", quantity: 2, price: 29.99)]
        )
    ),
    EventData(
        eventType: "OrderPaid",
        model: OrderEvent.paid(amount: 59.98, method: "credit-card")
    ),
    EventData(
        eventType: "OrderShipped",
        model: OrderEvent.shipped(trackingNumber: "TRACK-789")
    )
]

// Append to stream
try await client.appendStream(streamName, events: events) {
    $0.revision(expected: .any)
}

Read Event History

// Read all events for this order
let history = try await client.readStream(streamName) {
    $0.forward().startFrom(revision: .start)
}

for try await response in history {
    if let event = try response.event {
        print("[\(event.created)] \(event.eventType)")
        // Reconstruct state or update read models
    }
}

Subscribe to New Events

// React to new orders in real-time
let subscription = try await client.subscribeToStream("$ce-order") {
    $0.fromStart()
}

for try await event in subscription {
    // Update dashboard, send notifications, etc.
    await handleNewOrderEvent(event)
}

🔍 Key Features Deep Dive

1. Type-Safe by Design

// ❌ Stringly-typed (common in other languages)
store.append("order-123", "OrderCreated", "{\"data\": \"...\"}")

// ✅ Type-safe Swift
struct OrderCreated: Codable {
    let customerId: String
    let items: [Item]
}

let event = EventData(
    eventType: "OrderCreated",
    model: OrderCreated(customerId: "123", items: [...])
)
try await client.appendStream("order-123", events: [event])

The compiler ensures you can't mix up event types or forget required fields.

2. Modern Concurrency

Full support for Swift's async/await:

// Async/await throughout
try await client.appendStream(...)

// AsyncSequence for streaming
for try await event in client.readStream(...) {
    await process(event)
}

// Subscriptions work beautifully
let subscription = try await client.subscribeToStream("orders")
for try await event in subscription {
    await updateReadModel(event)
}

3. Optimistic Concurrency Built-in

Prevent race conditions with optimistic concurrency control:

// Ensure the stream is at expected revision
try await client.appendStream("cart-123", events: [event]) {
    $0.revision(expected: .specific(5))
}

// Throws if someone else modified the stream
// Your application can retry with the latest state

4. Production-Ready Features

✅ Connection management with automatic reconnection
✅ TLS/SSL support for secure connections
✅ Cluster configuration for high availability
✅ Projection management for building read models
✅ Persistent subscriptions for reliable event processing
✅ Swift 6 compatible with zero data-race safety

📚 Documentation That Actually Helps

One thing I'm particularly proud of is the comprehensive documentation. It's hosted on Swift Package Index and includes:

Getting Started - From zero to first event in 5 minutes
Appending Events - All the ways to write events
Reading Events - Querying your event streams
Projections - Building read models

Full API documentation is also available for every public type and method.

🏗️ Why Build This From Scratch?

Why gRPC?

I chose gRPC over HTTP for several reasons:

Performance - Binary protocol, efficient streaming
Type Safety - Protocol Buffers give compile-time guarantees
Bi-directional Streaming - Perfect for subscriptions
Industry Standard - Used by major companies worldwide

Why Not Wrap Existing Clients?

I could have wrapped the .NET or Node.js clients, but that would feel un-Swift. Instead, I:

✅ Used idiomatic Swift APIs that feel natural
✅ Leveraged Swift's type system for safety
✅ Integrated with Swift Concurrency (async/await)
✅ Made it feel like a native Swift library

The result is a library that Swift developers will find familiar and comfortable.

🎯 Real-World Use Cases

Event Sourcing with KurrentDB-Swift is perfect for:

E-commerce Systems

Track every action: orders placed, payments processed, items shipped, returns initiated.

Financial Applications

Complete audit trail for transactions, account changes, and compliance.

Collaborative Tools

Track document edits, user actions, and maintain complete history.

IoT and Monitoring

Store sensor readings, device events, and system state changes.

Microservices

Event-driven architecture with reliable event distribution.

🔮 What's Next

The core functionality is solid and production-ready, but there's always more to do:

Planned Improvements

[ ] More comprehensive examples and tutorials
[ ] Performance benchmarks vs other language clients
[ ] Additional articles on CQRS patterns
[ ] Snapshotting strategies guide
[ ] Event versioning best practices

Community Input Wanted

I'd love to hear from you:

What features would be most valuable?
What pain points have you encountered?
What examples or documentation would help most?

Join the conversation in GitHub Discussions.

🚀 Get Started Today

Ready to try Event Sourcing with Swift?

Installation

// Package.swift
dependencies: [
    .package(url: "https://github.com/gradyzhuo/KurrentDB-Swift.git", from: "1.11.2")
]

Five-Minute Quickstart

Install Kurrent (if needed):

   docker run -d -p 2113:2113 \
     eventstore/eventstore:latest \
     --insecure --enable-atom-pub-over-http

Write your first event:

   import KurrentDB

   let client = KurrentDBClient(settings: .localhost())
   let event = EventData(eventType: "TestEvent", model: ["hello": "world"])
   try await client.appendStream("test-stream", events: [event])

Read it back:

   let events = try await client.readStream("test-stream")
   for try await event in events {
       print(event)
   }

That's it! You're doing Event Sourcing in Swift. 🎉

🤝 How You Can Help

KurrentDB-Swift is open source and community-driven. Here's how you can contribute:

⭐ Star the repo - Helps with discoverability
🔧 Try it out - The best feedback comes from real usage
🐛 Report issues - Found a bug? Let me know!
💡 Request features - What would make it better?
📖 Improve docs - Spot a typo or unclear explanation?
🔨 Contribute code - PRs welcome!
📣 Spread the word - Blog posts, tweets, talks

Every contribution helps make Server-Side Swift better for everyone.

💭 Why Server-Side Swift Needs This

Server-Side Swift is at an exciting inflection point. We have:

✅ Mature frameworks (Vapor, Hummingbird)
✅ Excellent tooling
✅ Great performance
✅ Code sharing with iOS/macOS

But to compete with Node.js, Go, and Rust ecosystems, we need robust libraries for common architectural patterns. Event Sourcing is one of those critical patterns.

KurrentDB-Swift is a step toward making Server-Side Swift a first-class citizen for building complex, scalable, event-driven systems.

🙏 Acknowledgments

This project wouldn't exist without:

The Kurrent team for building an excellent event store
The grpc-swift team for solid gRPC implementation
The Swift Server Work Group for pushing the ecosystem forward
The Swift community for feedback and encouragement
Everyone who has contributed or provided input

📚 Resources

🎯 Final Thoughts

If you're building systems that need:

Complete audit trails
Event-driven architecture
CQRS patterns
Temporal queries
Complex business logic with full history

Give KurrentDB-Swift a try. It's production-ready, well-documented, actively maintained, and built specifically for Swift developers.

Let's make Server-Side Swift the go-to choice for event-driven systems. 🚀

About the Author

Hi! I'm Grady Zhuo, a Swift developer passionate about Server-Side Swift and Event Sourcing. I built KurrentDB-Swift to fill a gap in the Swift ecosystem and help make event-driven architecture accessible to Swift developers.

Let's connect:

💻 GitHub: @gradyzhuo
🐦 Twitter/X: @gradyzhuo
💼 LinkedIn: gradyzhuo

Questions? Thoughts? Feedback?

I'd love to hear from you! Leave a comment below, open a discussion on GitHub, or reach out on social media. Let's build something amazing together! 🎉