# CQRS: decisions and views

Command Query Responsibility Segregation separates the model used to change
state from the model used to read it. A command expresses intent; a query asks for
information. Separate models can share one database and one process.

## Commands express business tasks

`ObserveExternalProject` applies a prepared, qualified source observation. Its
handler checks the target, admission, source ownership and expected version before
calling Project behaviour. A material change saves the root. An unchanged complete
read records source-success evidence while preserving the material revision.

Read the [command](../../../services/beto/contexts/project/application/commands/observe_external_project.go).
A stable command identity and unchanged material input recover a recorded outcome
on retry. A new business attempt receives a new command identity.

## Queries return useful representations

`GetProjectIntegrationSnapshot` returns canonical Project state and source status.
It uses a read repository and explicit authorisation. Its freshness calculation
belongs to the query's contract.

<!-- example: {"path":"services/beto/contexts/project/application/queries/get_project_integration_snapshot.go","symbol":"type GetProjectIntegrationSnapshotQueryHandler struct"} -->

Read the [query implementation](../../../services/beto/contexts/project/application/queries/get_project_integration_snapshot.go)
and [published boundary](../../../contracts/project/messaging/README.md).
Queries preserve revisions, missing-resource behaviour and complete or explicitly
paginated results. Silent truncation can change an access decision.

## Views, projections and freshness

A read model answers a question. A projection maintains a representation from
source information, often asynchronously. Each consumer owns its local view and
its recovery policy. An event's arrival alone cannot establish that every related
projection is current.

Project has separate material-state and authority revision streams. An unchanged
source read can renew authority without changing the aggregate's material state.
Consumers must retain the source's validity and ordering semantics. Read the owner
contract before combining streams into a local access decision.

Browser delivery uses server-authorised Centrifugo subscriptions and typed Protobuf
projections. Queries reconcile state after gaps; revision checks prevent delayed
responses replacing newer data. [CLIENT-SUBSCRIPTIONS.md](../../../CLIENT-SUBSCRIPTIONS.md)
defines the platform rules.

CQRS adds representations and mappings. Use the separation where it clarifies
business decisions, read needs or recovery. It does not require separate databases
or an event-sourced aggregate.

Next: [Event-driven architecture](event-driven-architecture.md).

Adapted from the [architecture reference](attribution.md), with Pharos examples.