Document Library - CQRS & Event Sourcing Implementation

A Swift implementation of a document management system using CQRS (Command Query Responsibility Segregation) and Event Sourcing patterns, with CRDT (Conflict-Free Replicated Data Types) for multi-device synchronization.

🎯 Overview

This project demonstrates a production-ready implementation of event-sourced architecture with:

• ✅ Complete CQRS separation of write and read models
• ✅ Event Sourcing with append-only event log
• ✅ CRDT Last-Write-Wins for conflict resolution
• ✅ Multi-device synchronization with eventual consistency
• ✅ Tombstone pattern for permanent deletes
• ✅ Comprehensive test coverage (32 tests)

🏗️ Architecture

CQRS Flow

Commands → Handler → Aggregate → Events → EventStore → Projection → Queries

Components

Write Side (Command)

• Commands: CreateDocument, RenameDocument, DeleteDocument
• DocumentAggregate: Validates business rules and emits events
• DocumentHandler: Orchestrates command processing
• EventStore: Append-only log with observer pattern

Read Side (Query)

• LibraryProjection: Reconstructs current state from events
• Live Updates: Observer pattern for real-time projection updates
• Queries: getDocuments(), getDocument(byId:), getLibrary()

Sync

• SyncAPI: Protocol for remote event synchronization
• MockSyncAPI: In-memory implementation for testing
• SyncManager: Orchestrates push/pull operations

🔄 CRDT Conflict Resolution

Last-Write-Wins (LWW)

Each document operation has a timestamp. When conflicts occur:

• Rename vs Rename: Latest timestamp wins
• Delete vs Any: Delete always wins (tombstone)
• Out-of-order events: Handled correctly via per-document timestamps

Tombstone Pattern

Once a document is deleted, it cannot be recreated, even if a later creation event arrives (prevents resurrection).

📁 Project Structure

Library/
├── Sources/Library/
│   ├── Commands/           # Command definitions
│   ├── Events/             # Event definitions
│   ├── Models/             # Domain models
│   ├── Services/           # Core business logic
│   │   ├── DocumentAggregate.swift
│   │   ├── DocumentHandler.swift
│   │   ├── EventStore.swift
│   │   └── LibraryProjection.swift
│   └── Sync/               # Synchronization
│       ├── SyncAPI.swift
│       ├── MockSyncAPI.swift
│       └── SyncManager.swift
└── Tests/LibraryTests/
    ├── DocumentHandlerTests.swift      # Command & validation tests
    ├── LibraryProjectionTests.swift    # Projection & observer tests
    ├── CRDTTests.swift                 # Conflict resolution tests
    ├── SyncTests.swift                 # Synchronization tests
    ├── MultiDeviceMergeTests.swift     # Multi-device scenarios
    └── End2EndTests.swift              # Complete CQRS flows

🚀 Getting Started

Build

swift build

Run Tests

swift test

🧪 Test Coverage

32 comprehensive tests covering all functional requirements:

Category	Tests	Coverage
Command Handler	9	Command execution & validation
Projection	5	Read model & live updates
CRDT	4	Conflict resolution & LWW
Sync	5	API & multi-device sync
Multi-Device Merge	4	EventStore merging scenarios
End-to-End	4	Complete CQRS flows

Key Test Scenarios

✅ Single Device

• Create → Rename → Delete lifecycle
• Real-time projection updates

✅ Multi-Device Sync

• Device A creates docs, Device B pulls and sees them
• Both devices converge to identical state

✅ Offline Edits + Merge

• Both devices edit same document offline
• LWW resolves conflicts on sync

✅ Delete Conflicts

• Delete always wins over rename (tombstone)
• Deleted documents stay deleted