Use one model to change state.
Use another model to read state.

Command Service -> Event Bus -> Read Service

Which command model protects invariants?
Which query model serves which user journey?
How stale may each query be?
How is projection lag measured?
Can read models be rebuilt?
Who owns authorization on the query side?
What happens when projection fails?
Can the system explain why command success is not visible yet?

Domain aggregate grows query helpers.
Repository exposes ad hoc joins.
API returns persistence entities.
Write transaction includes read concerns.
Read endpoint leaks internal write schema.
Every UI request forces domain model contortion.

{
  "commandId": "cmd-9001",
  "type": "ApproveEnforcementDecision",
  "decisionId": "DEC-2026-00112",
  "approvedBy": "user-117",
  "expectedVersion": 8,
  "reason": "Meets statutory threshold"
}

public class EnforcementDecision {
    private String caseTitle;
    private String partyName;
    private String officerDisplayName;
    private String latestEvidenceSummary;
    private List<TimelineRow> timeline;
    private List<SearchFacet> facets;

    public void approve(...) { ... }
}

public final class EnforcementDecision {
    private DecisionId id;
    private DecisionStatus status;
    private PolicyVersion policyVersion;
    private long version;

    public DecisionApproved approve(ApproveDecision command, ApprovalPolicy policy) {
        if (status != DecisionStatus.READY_FOR_APPROVAL) {
            throw new DomainRuleViolation("Decision is not ready for approval");
        }
        policy.verifyApproval(command, this);
        return new DecisionApproved(id, command.approvedBy(), policyVersion, command.reason());
    }
}

CREATE TABLE decision_work_queue_view (
    decision_id          TEXT PRIMARY KEY,
    case_id              TEXT NOT NULL,
    case_title           TEXT NOT NULL,
    party_display_name   TEXT NOT NULL,
    status               TEXT NOT NULL,
    risk_band            TEXT NOT NULL,
    assigned_team_id      TEXT NOT NULL,
    due_at               TIMESTAMPTZ,
    days_until_due        INTEGER,
    last_activity_at      TIMESTAMPTZ,
    projection_position   BIGINT NOT NULL,
    updated_at            TIMESTAMPTZ NOT NULL
);

if (decisionWorkQueueRow.status().equals("READY")) {
    jdbc.update("update decision_work_queue_view set status='APPROVED' ...");
}

Query API shows READY.
User sends ApproveDecision command.
Command model validates and commits.
Projector updates view.

update decision table
insert decision_approval audit row
insert outbox event DecisionApproved
commit

read outbox/broker event
update decision_work_queue_view
update decision_detail_view
checkpoint event position

com.example.enforcement
  command
    api
    application
    domain
    persistence
  query
    api
    projection
    model
    persistence
  shared
    ids
    errors
    telemetry

@AnalyzeClasses(packages = "com.example.enforcement")
class CqrsArchitectureTest {
    @ArchTest
    static final ArchRule commandDoesNotDependOnQuery = noClasses()
        .that().resideInAPackage("..command..")
        .should().dependOnClassesThat().resideInAPackage("..query..");

    @ArchTest
    static final ArchRule queryDoesNotUseCommandRepositories = noClasses()
        .that().resideInAPackage("..query..")
        .should().dependOnClassesThat().resideInAPackage("..command.persistence..");
}

PATCH /decisions/DEC-1
{
  "status": "APPROVED"
}

POST /decisions/DEC-1/approval-requests
Idempotency-Key: cmd-9001
If-Match: "version-8"

{
  "reason": "Meets statutory threshold",
  "policyVersion": "ENF-POLICY-2026.04"
}

200 OK
{
  "decisionId": "DEC-1",
  "status": "APPROVED",
  "version": 9
}

202 Accepted
{
  "commandId": "cmd-9001",
  "statusUrl": "/commands/cmd-9001",
  "expectedReadModelPosition": 802711
}

GET /decision-work-queue?teamId=TEAM-7&status=READY_FOR_APPROVAL&sort=dueAt&pageSize=50&pageToken=...

{
  "items": [
    {
      "decisionId": "DEC-2026-00112",
      "caseId": "CASE-2026-00091",
      "caseTitle": "Regional enforcement review",
      "partyDisplayName": "Acme Trading Ltd",
      "riskBand": "HIGH",
      "dueAt": "2026-07-07T09:00:00Z",
      "status": "READY_FOR_APPROVAL"
    }
  ],
  "page": {
    "nextPageToken": "..."
  },
  "freshness": {
    "projectionPosition": 802700,
    "lagSeconds": 2,
    "asOf": "2026-07-05T10:15:32Z"
  }
}

Decision work queue must reflect command events within 5 seconds at p99.

Approval submitted.
Work queue update pending.

{
  "decisionId": "DEC-1",
  "committedPosition": 802711
}

{
  "freshness": {
    "projectionPosition": 802711,
    "caughtUpToRequestedPosition": true
  }
}

public final class DecisionWorkQueueProjector {
    private final DecisionWorkQueueRepository repository;
    private final ProjectionCheckpointStore checkpointStore;

    public void on(EventEnvelope envelope) {
        if (checkpointStore.hasProcessed("decision-work-queue", envelope.position())) {
            return;
        }

        switch (envelope.event()) {
            case DecisionDrafted e -> repository.insertDraft(e.decisionId(), e.caseId(), envelope.position());
            case DecisionMarkedReady e -> repository.markReady(e.decisionId(), e.dueAt(), envelope.position());
            case DecisionApproved e -> repository.removeFromQueue(e.decisionId(), envelope.position());
            case DecisionRejected e -> repository.removeFromQueue(e.decisionId(), envelope.position());
            case CaseRiskBandChanged e -> repository.updateRiskBand(e.caseId(), e.riskBand(), envelope.position());
            default -> { }
        }

        checkpointStore.markProcessed("decision-work-queue", envelope.position());
    }
}

CREATE TABLE projection_checkpoint (
    projection_name       TEXT PRIMARY KEY,
    last_position         BIGINT NOT NULL,
    updated_at            TIMESTAMPTZ NOT NULL
);

CREATE TABLE projection_checkpoint (
    projection_name       TEXT NOT NULL,
    partition_id          TEXT NOT NULL,
    last_offset           BIGINT NOT NULL,
    updated_at            TIMESTAMPTZ NOT NULL,
    PRIMARY KEY(projection_name, partition_id)
);

1. Create new projection table/index with version suffix.
2. Replay source events/messages into new projection.
3. Compare counts/checksums/sample rows.
4. Run shadow queries against new projection.
5. Switch query API to new projection.
6. Keep old projection temporarily for rollback.
7. Retire old projection after confidence window.

Authorization is enforced on command side, so query side is safe.

Can this user see this row?
Can this user see this field?
Can this user see this tenant?
Can this user see historical/redacted data?
Can this user search by this attribute?
Can this user export results?

CREATE TABLE decision_work_queue_view (
    decision_id        TEXT PRIMARY KEY,
    tenant_id          TEXT NOT NULL,
    assigned_team_id   TEXT NOT NULL,
    visibility_scope   TEXT NOT NULL,
    sensitivity_level   TEXT NOT NULL,
    status             TEXT NOT NULL,
    due_at             TIMESTAMPTZ
);

SELECT *
FROM decision_work_queue_view
WHERE tenant_id = :tenantId
  AND assigned_team_id = ANY(:userTeamIds)
  AND sensitivity_level <= :maxSensitivity
ORDER BY due_at ASC
LIMIT :limit;

At request time, call several services and combine response.

Before request time, consume changes and build query-optimized view.

If query is rare, simple, and freshness-critical, use composition.
If query is frequent, expensive, user-facing, and shape-specific, use read model.

BI dashboard queries production read model with huge date range.

Operational read model serves UI.
Data product/warehouse serves analytics.
Both are sourced from contracted events/CDC with lineage.

public void markReady(DecisionMarkedReady event, long streamVersion) {
    repository.updateIfNewer(
        event.decisionId(),
        row -> row.status("READY_FOR_APPROVAL"),
        streamVersion
    );
}

UPDATE decision_detail_view
SET status = :status,
    source_version = :sourceVersion
WHERE decision_id = :decisionId
  AND source_version < :sourceVersion;

DecisionMarkedReady from Decision Service
CaseRiskBandChanged from Case Service
PartyNameCorrected from Party Service

decision_source_version
case_source_version
party_source_version

A projection must produce the same read model if the same event is processed twice.

pause serving if unsafe
fix projector
rebuild projection
compare checksums
switch read path
record incident evidence

projection_lag_seconds{projection="decision-work-queue"}
projection_lag_events{projection="decision-work-queue"}
projection_last_processed_position{projection="decision-work-queue"}
projection_error_total{projection="decision-work-queue", eventType="DecisionApproved"}
projection_rebuild_duration_seconds{projection="decision-work-queue"}
query_latency_seconds{endpoint="decision-work-queue"}
query_result_stale_total{endpoint="decision-work-queue"}

99% of DecisionApproved events are visible in decision_detail_view within 3 seconds over 30 days.

Page if projection lag > 60 seconds for 10 minutes for a user-facing read model.
Ticket if projection lag > 10 seconds for 30 minutes for non-critical read model.

@RestController
@RequestMapping("/decisions/{decisionId}")
public final class DecisionCommandController {
    private final ApproveDecisionHandler handler;

    @PostMapping("/approval-requests")
    public ResponseEntity<ApproveDecisionResponse> approve(
        @PathVariable String decisionId,
        @RequestHeader("Idempotency-Key") String idempotencyKey,
        @RequestHeader("If-Match") String ifMatch,
        @RequestBody ApproveDecisionRequest request,
        Principal principal
    ) {
        ApproveDecision command = new ApproveDecision(
            new DecisionId(decisionId),
            new UserId(principal.getName()),
            request.reason(),
            ExpectedVersion.fromIfMatch(ifMatch),
            new IdempotencyKey(idempotencyKey)
        );

        ApproveDecisionResult result = handler.handle(command);
        return ResponseEntity.ok(new ApproveDecisionResponse(
            result.decisionId().value(),
            result.newVersion(),
            result.committedPosition()
        ));
    }
}

public final class ApproveDecisionHandler {
    private final DecisionRepository repository;
    private final Outbox outbox;
    private final TransactionTemplate tx;
    private final IdempotencyStore idempotencyStore;

    public ApproveDecisionResult handle(ApproveDecision command) {
        return idempotencyStore.execute(command.idempotencyKey(), () ->
            tx.execute(status -> {
                EnforcementDecision decision = repository.getForUpdate(command.decisionId());
                decision.assertVersion(command.expectedVersion());

                DecisionApproved event = decision.approve(command);

                repository.save(decision);
                long position = outbox.append(event, Metadata.from(command));

                return new ApproveDecisionResult(decision.id(), decision.version(), position);
            })
        );
    }
}

@RestController
@RequestMapping("/decision-work-queue")
public final class DecisionWorkQueueController {
    private final DecisionWorkQueueQueryService queryService;

    @GetMapping
    public WorkQueueResponse search(
        @RequestParam String teamId,
        @RequestParam Optional<String> status,
        @RequestParam Optional<String> pageToken,
        @RequestParam(defaultValue = "50") int pageSize,
        Principal principal
    ) {
        WorkQueueQuery query = new WorkQueueQuery(
            new TeamId(teamId),
            status.map(DecisionStatus::valueOf),
            PageRequest.from(pageToken, pageSize),
            UserContext.from(principal)
        );

        return queryService.search(query);
    }
}

public final class DecisionWorkQueueQueryService {
    private final DecisionWorkQueueRepository repository;
    private final QueryAuthorizer authorizer;
    private final ProjectionFreshnessService freshnessService;

    public WorkQueueResponse search(WorkQueueQuery query) {
        authorizer.assertCanViewTeamQueue(query.user(), query.teamId());

        Page<DecisionWorkQueueRow> rows = repository.search(
            query.teamId(),
            query.status(),
            query.page()
        );

        ProjectionFreshness freshness = freshnessService.get("decision-work-queue");

        return WorkQueueResponse.from(rows, freshness);
    }
}

validate command
update write store
insert outbox event
commit

read event
upsert read model
update checkpoint
commit

Use plain CRUD when write/read model fit is good.
Use internal CQRS when read and write responsibilities are diverging.
Use separate read model when query performance/shape demands it.
Use separate query service only when deployment/scale/ownership justify it.
Use event sourcing only when event history should be source of truth.

CaseCommandService
CaseQueryService
PartyCommandService
PartyQueryService
EvidenceCommandService
EvidenceQueryService

Every team directly queries decision_work_queue_view.

Expose query API or published data product.
Keep read store private to owning service/query service.

Every field change emits event.
Every read model listens to everything.
Nobody owns semantics.

Events represent domain facts.
Read models subscribe to relevant facts.
Event catalog documents meaning and owner.

It will be eventually consistent.
No lag metric.
No user explanation.
No reconciliation.
No retry handling.

Projection lag SLO.
Freshness metadata.
Retry-safe projectors.
Rebuild runbook.

Command service and query service implement separate hard-coded authorization rules.

Shared policy decision model or policy service/library with versioned tests.
Projected visibility fields.
Query-side enforcement.

[ ] Why is CQRS needed here?
[ ] What pain exists in the unified model?
[ ] What is the command model responsible for?
[ ] What invariants does the command model protect?
[ ] What query journeys does the read model serve?
[ ] What is the freshness/staleness contract?
[ ] Is read-after-write behavior documented?
[ ] How are read models built?
[ ] Are projectors idempotent?
[ ] Is projection lag measured?
[ ] Can read models be rebuilt?
[ ] Who owns query-side authorization?
[ ] Are sensitive fields minimized in read models?
[ ] How are event/schema changes tested?
[ ] What happens when projection fails?
[ ] Is CQRS internal or separate deployable? Why?
[ ] Is API composition a simpler alternative?
[ ] Is event sourcing necessary, or is outbox enough?

# ADR: Apply CQRS for <Capability/Use Case>

## Context
- Current model pain:
- Query workload:
- Write invariants:
- Performance/SLO requirement:
- Consistency requirement:

## Decision
We will apply CQRS by separating ...

## Command Model
- Command endpoints:
- Invariants:
- Transaction boundary:
- Idempotency/concurrency:

## Query Model
- Query endpoints:
- Read models:
- Storage:
- Filters/sorting/pagination:
- Authorization:

## Projection Model
- Source events/outbox/CDC:
- Projectors:
- Checkpointing:
- Rebuild strategy:
- Lag SLO:

## Consistency Contract
- Read-after-write behavior:
- Bounded staleness:
- UX handling:

## Alternatives Rejected
- CRUD model:
- API composition:
- Reporting warehouse:
- Event sourcing:

## Consequences
- Benefits:
- Added complexity:
- Operational burden:
- New failure modes:

The write model is becoming too strict for queries.
The read model is becoming too denormalized for writes.
The same model cannot satisfy correctness and query performance cleanly.

The team only needs simple CRUD.
The read model would be copied blindly from write tables.
No one can define staleness tolerance.
No one will operate projection lag and rebuild.

Commands protect truth.
Queries serve experience.
Projections connect them with explicit consistency and operational contracts.

Should we use CQRS because microservices do CQRS?

Where are reads and writes pulling the model in different directions?
What is the cheapest separation that resolves the tension?
Can the team operate the consistency gap introduced by that separation?