CQRS Architecture: Mermaid Flowchart Diagram

About Source

CQRS (Command Query Responsibility Segregation) is an architectural pattern that separates the write model (commands that change state) from the read model (queries that return data), allowing each side to be optimized, scaled, and evolved independently.

What the diagram shows

The diagram splits into two clear paths from the Client. On the left, a Command (create, update, delete) flows to the Command Handler, which validates the intent and writes to the Write Store — a normalized relational database optimized for consistency and transactional integrity. After a successful write, a Domain Event is published to an Event Bus.

On the right, Query requests flow to the Query Handler, which reads from a Read Store — a denormalized projection database, search index, or materialized view optimized purely for fast retrieval. An Event Projector subscribes to the Event Bus and continuously updates the Read Store to reflect the latest committed state, keeping the two sides eventually consistent.

Why this matters

When read and write workloads have very different characteristics — for example, thousands of reads per second against tens of writes — a single unified model forces both to share the same indexes, schema design, and scaling strategy. CQRS breaks that coupling: the write side can use a strongly-typed domain model with strict validation, while the read side uses flat, pre-joined projections that return in a single query.

The trade-off is eventual consistency: a command may complete successfully before its effect appears in the read store. Systems using CQRS must handle this lag explicitly. For the async backbone that connects both sides, see Event Driven System. For replication patterns on the read side, see Database Replication.

Frequently asked questions

CQRS (Command Query Responsibility Segregation) is an architectural pattern that separates the write model — commands that mutate state — from the read model — queries that return data — allowing each side to be optimized, scaled, and evolved independently.

Commands flow to a Command Handler that writes to a normalized Write Store and publishes domain events to an Event Bus. An Event Projector consumes those events and updates a denormalized Read Store optimized for fast retrieval. Query Handlers read exclusively from the Read Store without touching the Write Store.

Use CQRS when read and write workloads have significantly different characteristics — such as thousands of reads per second against tens of writes — or when the read model needs to serve multiple projections (search indexes, materialized views) that would be expensive to derive at query time from a single normalized schema.

The most common mistake is applying CQRS to simple CRUD services where the overhead of dual models and eventual consistency outweighs the benefits. Other pitfalls include not making consumers idempotent (leading to duplicate projections on replay), and under-estimating the engineering effort to manage projection lag and event schema evolution.

CQRS separates read and write models but does not prescribe how state is stored. Event sourcing stores all state changes as an immutable sequence of domain events, rebuilding current state by replaying them. The two patterns are often combined — CQRS provides the read/write split while event sourcing provides the audit log — but each can be used independently.

mermaid

flowchart LR
    Client([Client])

    Client -->|Command\ncreate / update / delete| CH[Command Handler]
    Client -->|Query\nread request| QH[Query Handler]

    CH --> Validate{Validate\nCommand}
    Validate -->|Invalid| Reject[Return Error\nto Client]
    Validate -->|Valid| WriteStore[(Write Store\nNormalized DB)]
    WriteStore --> Event[Domain Event\nPublished]
    Event --> Bus[[Event Bus]]
    Bus --> Projector[Event Projector]
    Projector --> ReadStore[(Read Store\nDenormalized\nProjection)]
    QH --> ReadStore