backend-cqrs-patterns

Backend CQRS Patterns

Purpose

Separate read and write models so each can be optimized independently — write side for consistency and validation, read side for query performance and projection flexibility.

Agent Protocol

Trigger

Exact user phrases: "CQRS", "command query segregation", "separate read write", "command model", "query model", "read model", "write model", "materialized view", "command handler", "query handler", "command bus", "query bus".

Input Context

• Whether the system is greenfield or existing.
• Current data access pattern (CRUD, repository, ORM).
• Read-to-write ratio and query complexity.
• Consistency requirements (strong vs eventual).

Output Artifact

CQRS design as text. No file unless requested.

Response Format

Command: {name}
Handler: {class/module}
Validation: {rules}
Write model: {storage}

Query: {name}
Handler: {class/module}
Read model: {storage/projection}

Completion Criteria

• Commands and queries are in separate model classes.
• Commands return success/failure, never data.
• Queries return data, never cause side effects.
• Write model uses transactional consistency.
• Read model tolerates eventual consistency.
• Command validation is separate from command execution.
• Synchronization mechanism defined (if separate stores).

Max Response Length

Per command/query: 6 lines. Full design: 30 lines.

Architecture Decision Tree

Should I Use CQRS?

Are read and write data shapes significantly different?
  ├── Yes → CQRS candidate
  └── No → Is the read-to-write ratio > 10:1?
            ├── Yes → Consider CQRS for read optimization
            └── No → Is query complexity causing write model compromises?
                      ├── Yes → CQRS may help separate concerns
                      └── No → Simple CRUD is sufficient — skip CQRS

Same Database vs Separate Databases?

Do queries require different storage technology than writes?
  ├── Yes → Separate databases (e.g., PG for writes, Elasticsearch for reads)
  └── No → Can you use materialized views or same-DB projections?
            ├── Yes → Same database, different models (simpler)
            └── No → Separate databases