cqrs

CQRS (Command Query Responsibility Segregation)

When to Activate

Activate when:

• Designing read-heavy or write-heavy systems separately
• Implementing complex domain models with divergent read/write logic
• Building systems that need different data representations for reading vs. writing
• Scaling read and write workloads independently
• Implementing event sourcing alongside specialized read models

Steps

1. Separate Command and Query Models

Aspect	Command	Query
Purpose	Modify state	Read state
Returns	Void / ACK	Data
Side Effects	Yes	No
Complexity	Business logic	Data shaping

Commands and queries should use different models with different schemas optimized for their specific use case.

2. Design Command Side

• Commands are intent-based (present tense: PlaceOrder, UpdatePrice)
• Validate business rules before executing
• Return success/failure, not data
• Keep command handlers small and focused

interface Command {
  id: string;          // Correlation ID
  type: string;        // Command type
  payload: unknown;    // Command data
  metadata: {
    userId: string;
    timestamp: string;
    correlationId: string;
  };
}

interface CommandHandler<T extends Command> {
  execute(command: T): Promise<CommandResult>;
}

3. Design Query Side

• Queries are data-focused (past/read tense: GetUserOrders, FindActiveProducts)
• Queries should be side-effect free
• Return read-optimized data structures (possibly denormalized)
• Support pagination, filtering, sorting

interface Query {
  id: string;
  type: string;
  parameters: Record<string, unknown>;
  pagination?: { page: number; limit: number };
  sorting?: { field: string; direction: 'asc' | 'desc' }[];
}

interface QueryHandler<T extends Query> {
  execute(query: T): Promise<QueryResult>;
}

4. Implement Synchronization

When commands and queries share data: