DDD CQRS Architecture

CQRS (Command Query Responsibility Segregation) — L1/L2/L3 adoption, Event Sourcing, idempotency, and integration with five DDD architectures.

When to Use This Skill

Trigger keywords: CQRS, read-write separation, Event Sourcing, event sourcing, Command Bus, Query Model, domain event, Domain Event, idempotency, eventual consistency, projection, materialized view

Workflow

Step 1: 判断是否需要 CQRS → 确认读写模式是否显著分化
Step 2: 选择 CQRS 级别 → L1/L2/L3
Step 3: 设计命令模型 → Command → Handler → 领域事件
Step 4: 设计查询模型 → Query → Handler → DTO
Step 5: 实现事件同步（L2/L3）→ Outbox → 发布器 → 投影
Step 6: 按架构集成 → 根据 Layered/Onion/Hexagonal/Clean/COLA

When to Use CQRS

Applicable Scenarios

Significant divergence between read and write patterns: Write operations and read operations require different data structures and optimization strategies
High-concurrency writes: Writes require ACID guarantees, while reads can accept eventual consistency
Multiple-view requirements: The same data must be presented in multiple forms, such as lists, details, statistics, and search results
Audit-trail requirements: The complete history of all state changes must be recorded
The team has event-driven capabilities: The team understands eventual consistency and Event Sourcing concepts

Upgrade Path

CRUD 够用（读=写）         → 单模型，无需 CQRS
  ↓
L1 模型分离                → CommandService / QueryService 分离，共享 DB
  ↓
L2 数据库分离               → Command DB + Query DB，事件同步
  ↓
L3 Event Sourcing          → EventStore + Projection

Inapplicable Scenarios

Scenario	Alternative
Simple CRUD where reads and writes are identical	Use a single model without CQRS
Prototype or one-off project	Skip CQRS
The team is unfamiliar with event-driven architecture	First use `ddd-event-storming` to establish event-driven thinking
Extremely high strong-consistency requirements	Evaluate the cost of distributed transactions

CQRS Core Principles

Dimension	Command Side (Write)	Query Side (Read)
Responsibility	Handle state changes and enforce business rules	Return data views without business logic
Model	Command Model (command object + aggregate root)	Query Model (DTO + materialized view)
Storage	Write DB (3NF, ACID)	Read DB (denormalized, optimized for queries)
Consistency	Strong consistency (within an aggregate)	Eventual consistency (across aggregates or services)
Output	Domain events	DTO / View Model

L1/L2/L3 Adoption Strategy

L1 — Model Separation

Lowest cost: separate Command/Query Services only at the code layer while sharing a database. Suitable when read and write data structures are the same but their logic should remain separate. Reference example:

examples/06-order-l1-model-separation.md

L2 — Database Separation

Moderate cost: separate the Command DB and Query DB, with synchronization through domain events. Suitable when read workloads are heavy or require an independent optimization strategy. Reference example:

examples/07-order-l2-db-separation.md

L3 — Event Sourcing

Highest cost: use the event stream as the single source of truth and rebuild read models through projections. Suitable for audit trails, time-travel queries, and event replay. Reference example:

examples/08-order-l3-event-sourcing.md

Event Lifecycle

领域行为 → 构建 DomainEvent → 持久化 → EventBus 发布
                                        → 本地处理器 (同步)
                                        → MQ 外发 (异步, 跨服务)

Publishing Strategies

Polling publication (scheduled table scans): 1–5s latency, low complexity, suitable for small-to-medium traffic
CDC (Debezium binlog): <100ms latency, moderate complexity, suitable for high-traffic, low-latency scenarios
Transaction commit callback: <10ms latency, low complexity, suitable for Spring projects

Detailed reference:

references/02-cqrs-events.md

Idempotency Design

Strategy	Overhead	Reliability	Scenario
Event deduplication table	Medium	★★★	Mission-critical financial events
State-machine guard	Low	★★★	State-driven events
Redis + TTL	Low	★★☆	Non-critical notifications
Business idempotency	Low	★★★	Simple operations

Detailed reference, including code examples:

references/07-event-governance.md

CQRS Integration Patterns Across Architectures

Architecture	Integration Point	Directory Structure
Layered	Separate Command/Query Services in the Application layer	`app/service/command/` + `app/service/query/`
Onion	Command/Query UseCase interfaces in the Core layer	`core/application/command/` + `core/application/query/`
Hexagonal	Command Port + Query Port in the Port layer	`domain/port/command/` + `domain/port/query/`
Clean	Command Interactor + Query Interactor in the UseCase layer	`usecase/interactor/command/` + `usecase/interactor/query/`
COLA	Command + Query submodules in the App layer	`app/command/` + `app/query/`

Detailed reference:

examples/04-multi-architecture-integration.md

Gotchas

Premature upgrade to L2/L3: First validate the value of CQRS at L1; most projects only need L1
The Query side directly queries the write database: A Query must never read tables from the Command-side database directly
Forgotten event idempotency: Consumers must implement idempotency to handle at-least-once delivery
Incompatible event versions: Changes to event structures must remain backward-compatible
Handling eventual consistency in the UI: Under L2/L3, the frontend must use polling or WebSocket
Oversized aggregates: Event-sourced aggregates should follow the small-aggregate principle

FAQ

Question	Answer
Does CQRS always introduce eventual consistency?	No. L1 does not require it, while L2/L3 do
Is Event Sourcing coupled to CQRS?	No. They can be used independently
When is the Outbox Pattern needed?	When reliable event publishing is required, to avoid the dual-write problem
What is the relationship between CQRS and microservices?	They are orthogonal and can be deployed within a monolith or across microservices
How complex can the query model become?	It can aggregate data across aggregates or services into denormalized materialized views

Rules

Rule	Description
The Command side must validate authorization	Authorization must be validated before executing a command
Event payloads must not contain sensitive data	Passwords, PII, and similar data should not appear in events
The Query side must not modify state	Query Handler/Service must not perform write operations
Write business data and the Outbox in the same transaction	Avoids the dual-write problem
Strong consistency within an aggregate; eventual consistency across aggregates	A single transaction should modify the state of at most one aggregate

Skill Boundary

✅ Good at Handling

Systems with significantly divergent read and write patterns, such as reporting versus transactional processing
Projects that require an event-driven architecture
Progressive implementation of the three CQRS levels: L1 model separation, L2 database separation, and L3 Event Sourcing
Integration patterns for five DDD architectures
Governance of the full domain event lifecycle, including publishing, subscription, idempotency, and compensation

⚠️ Requires Conditions

A base architecture has already been selected from Layered, Onion, Hexagonal, Clean, or COLA
The team understands eventual consistency and event-driven concepts
The business scenario genuinely requires read-write separation rather than simple CRUD

❌ Should Not Be Used (Out of Scope)

Simple CRUD where reads and writes are identical → CQRS is not applicable
Prototypes or one-off projects → CQRS should not be used
Teams unfamiliar with event-driven architecture → First use
```
ddd-event-storming
```
to establish event-driven thinking
Projects already using a CQRS framework such as Axon → The framework already includes the CQRS pattern

Security & Stability

Code templates are educational — replace URLs/credentials with env vars.
Command handlers must validate authorization. Never trust caller is authorized.
Event payloads must not contain sensitive data — events are stored and replayed.
Principle of least privilege: Command API and Query API should use different access-control permissions

Keywords

CQRS

read-write separation

Event Sourcing

event sourcing

Command Bus

Query Model

Command Model

domain event

Domain Event

eventual consistency

Eventual Consistency

Outbox Pattern

Transactional Outbox

Materialized View

Projection

Event Store

Idempotency

idempotency

L1/L2/L3

Clean Architecture CQRS

Hexagonal CQRS

COLA CQRS

References

Architecture CQRS Patterns

```
references/architecture/01-clean-ddd-hexagonal-cqrs.md
```
— CQRS & Domain Events: Commands, Queries, Read Models, Event Dispatcher, Outbox
```
references/02-cqrs-events.md
```
— CQRS domain events: event classification, event storage, projection strategies, and version management
```
references/03-cqrs-mindmap.md
```
— CQRS mind map: applicable scenarios and implementation strategies
```
references/04-ddd4j-cqrs-mindmap.md
```
— CQRS mind map: core concepts, architecture patterns, and components

Domain Events & Event Governance

```
references/07-event-governance.md
```
— Event governance: Outbox DDL, idempotency, retries, dead-letter handling, compensation, and reconciliation
```
references/domain-events/01-domain-events-deep.md
```
— Deep dive into domain events: event-driven design principles
```
references/06-domain-vs-integration-events.md
```
— Domain events vs. integration events: defining their boundaries
```
references/08-partme-06-domain-events.md
```
— Domain events in practice: an insurance underwriting case

Examples

examples/06-order-l1-model-separation.md

— Complete L1 model separation example

```
examples/07-order-l2-db-separation.md
```
— L2 database separation + event synchronization
```
examples/08-order-l3-event-sourcing.md
```
— Complete L3 Event Sourcing example
```
examples/04-multi-architecture-integration.md
```
— Comparison of CQRS integration across five architectures
```
examples/03-inventory-cqrs.md
```
— Inventory CQRS + idempotency strategy implementation

ddd-cqrs-architecture

NPX Install

Tags

SKILL.md Content (Chinese)