Getting Started with ddd_cqrs_es

Welcome to the lightweight, infrastructure-light Domain-Driven Design (DDD), CQRS, and Event Sourcing framework for Rust.

Welcome to ddd_cqrs_es! This library is a lightweight, high-performance Rust framework designed to help you construct highly reliable, testable, and maintainable software systems using the combined power of Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and Event Sourcing (ES).

The distinguishing design philosophy of this framework is that it is completely infrastructure-light. Your core domain logic—the rules that govern how your business operates—is kept entirely free of dependencies on databases, serialization formats, web frameworks, or asynchronous runtimes.

---

🚀 Installation

Add the crate as a dependency in your Cargo.toml:

[dependencies]
ddd_cqrs_es = "0.3.0-rc.7"

Feature Flags

Our framework is highly modular. You can enable specific adapters and engines depending on your production requirements.

Enabling Durable Database Adapters:

• SQLite Support: Enable the "sqlite" feature (uses the rusqlite driver under the hood).
• PostgreSQL Support: Enable the "postgres" feature (uses the postgres driver under the hood).
• MySQL Support: Enable the "mysql" feature (uses the mysql driver under the hood).
• Spin MySQL Helper: Enable "spin-mysql" for Spin SDK MySQL query execution.

Supported Backends:

• SQLite / Local File: Standard local embedded SQL.
• PostgreSQL: Stable high-performance relational database.
• MySQL: High-performance relational database with native stores plus a Spin runtime query helper ("spin-mysql").
• LibSQL / Turso: Supported for distributed edge SQL via the "wasi-libsql" query helper.
• Redis: Supported for async event store, checkpoints, and pub/sub notifications via "redis" / "wasi-redis" / "spin-redis".

Realtime and Notification Support:

The root crate provides durable stores, checkpoints, idempotency stores, and notification primitives. HTTP streaming is application-owned.

• PostgreSQL / SQLite / MySQL: Use durable events and checkpoints to drive polling, SSE, WebSocket, or worker pipelines in your application.
• Redis: Provides experimental async persistence plus notification-only pub/sub wake messages. Durable replay remains the source of truth.
• MySQL: MySQL does not provide a built-in pub/sub stream in this library; pair it with Redis, an outbox worker, binlog CDC, NATS, Kafka, or WebSocket fan-out when low-latency push notifications are required.

API Notes:

• Aggregates are loaded by the repository using the external stream ID; the Aggregate trait does not require an id() method.
• EventType is a serde-transparent newtype. Convert it with as_str() or into_string() when a database, UI, or protocol needs a plain string.
• SqlSchemaConfig table-name builders validate eagerly and return Result.
• Process managers can be coordinated by ProcessManagerRunner or AsyncProcessManagerRunner.
• execute_idempotent(...) is portable but not crash-atomic across separate stores. Use execute_idempotent_atomic(...) with native SQL stores for production request idempotency.

Feature	Description	Third-Party Dependencies
default	Standard local, thread-safe in-memory event store and memory projection runners.	None
sqlite	Stable SQLite event store, checkpoint store, idempotency store, snapshot store, and atomic idempotent append.	rusqlite
postgres	Stable PostgreSQL event store, checkpoint store, idempotency store, snapshot store, and atomic idempotent append.	postgres
mysql	Stable MySQL event store, checkpoint store, idempotency store, snapshot store, and atomic idempotent append.	mysql
spin-mysql	Experimental Spin SDK MySQL query helper.	spin-sdk
redis	Experimental async Redis event store, checkpoint store, pub/sub publisher, and command executor trait.	None
wasi-redis	Experimental raw RESP Redis client for generic Wasmtime/WASI runtimes.	redis
spin-redis	Experimental Spin SDK Redis client.	spin-sdk
wasi-http	Experimental outbound HTTP helper foundation for WASI runtimes.	wasip3, http, http-body-util, bytes
wasi-neon	Experimental Neon HTTP SQL query helper.	wasi-http
wasi-libsql	Experimental LibSQL/Turso Hrana HTTP query helper.	wasi-http
spin-sqlite	Experimental Spin SQLite host-call query helper.	spin-sdk
spin-postgres	Experimental Spin PostgreSQL host-call query helper.	spin-sdk
wasi-supabase-rpc	Experimental Supabase RPC query helper.	wasi-http

---

⚡ Quick 10-Second Example

Here is how simple it is to initialize our write path, tie it to an in-memory event ledger, and execute a transactional command:

use ddd_cqrs_es::{InMemoryEventStore, Repository, Metadata};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Initialize a thread-safe, local, in-memory event ledger
    let store = InMemoryEventStore::<BankAccount>::new();
    
    // 2. Bind the ledger to the repository coordinator
    let repo = Repository::new(store);
    let account_id = "account_abc123".to_owned();

    // 3. Execute a transactional command with audit tracking metadata!
    repo.execute(
        &account_id,
        BankAccountCommand::DepositMoney { amount: 100 },
        Metadata::new().with_actor_id("user_alice"),
    )?;

    // 4. Rebuild aggregate state instantly by replaying its historical facts
    let loaded = repo.load(&account_id)?;
    assert_eq!(loaded.state.balance(), 100);
    
    println!("Transaction committed! Balance is: ${}", loaded.state.balance());
    Ok(())
}

---

🗺️ How to Navigate This Documentation

We structured our guides as a structured, chronological path designed to take you from a complete beginner to building full-scale, distributed production applications:

Start with the CLI: ddd CLI

• What you’ll learn: Install the ddd command, scaffold a new app with ddd init, add domain events and commands with ddd add, enable Redis/gRPC/tracing capabilities, run Spin-focused apps, and use dry-run JSON for agent/MCP workflows.

Module 1: The Patterns (Theory)

• What you’ll learn: The architectural foundations. Read about Domain-Driven Design (aggregate boundaries, Ubiquitous Language), CQRS (separating write vs read pipelines), State Changes (command validation vs event application), Queries (read models), and Event Sourcing mechanics.

Module 2: Domain Modeling (Tutorial)

• What you’ll learn: Build a fully validated Bank Account domain step-by-step. Implement Commands, Events (implementing DomainEvent), Errors (handling invariants), and the core Aggregate Root struct.

Module 3: Domain Tests

• What you’ll learn: Write bulletproof business validations in microseconds. Learn why Event Sourcing is a unit-testing superpower and write elegant Given-When-Then tests using the Aggregate Test Fixture API.

Module 4: Configuring an Application

• What you’ll learn: Assemble your domain parts. Wire up the local InMemoryEventStore, write a custom Query Projection, and Assemble them together into a working execution loop.

Module 5: Building an Application (Production)

• What you’ll learn: Move to production. Start with Production Guarantees, define Error Handling and Transport Mapping, deploy durable SQLite, PostgreSQL, and MySQL stores, configure asynchronous Projections with Checkpoint tracking, review production Database Query Patterns, use experimental Redis persistence and realtime notifications, attach Metadata trace headers, write custom Event Upcasters for schema evolution, and Integrate with Web Frameworks (Axum).

Module 6: Fullstack SaaS (Spin + wasi-auth)

• What you’ll learn: Operate the production SaaS starter. wasi-auth fullstack covers Spin + outbox worker, auth/org product surfaces, and release topology. Use auth storage rollout and OAuth rollout for operators. For Leptos islands product chrome (soft-nav, sidebar persistence, skeleton rules), read Persistent chrome on Leptos islands. Scaffold with ddd init --preset fullstack (see ddd CLI).

Module 7: Leptos WASM SSR + Spin CQRS and Runtimes

• What you’ll learn: The counter-style implementation path (domain → Spin storage → projections → server APIs → UI → backends → execution), then Wasmtime vs Spin deployment trade-offs.

For documentation site navigation (which public pages are registered), see docs/docs.json. Internal roadmap and PRD notes under docs/prd/ and docs/PRD.md stay in the repo for maintainers and are not published in the sidebar.