cqrs-implementation

Define separate Command and Query dataclasses, register handlers in a CommandBus and QueryBus, and dispatch operations through the appropriate bus. Commands mutate the write model and emit events, while queries read from denormalized read models.

Inject the command bus into POST, PUT, and DELETE endpoints and the query bus into GET endpoints using FastAPI dependency injection. Commands return identifiers or status, while queries return view models like paginated order results.

A command expresses intent to change state and is validated and executed by a command handler against the write model. A query only retrieves data from the read model and never modifies state, allowing each side to use different schemas.

Use a read model synchronizer that polls the event store from a saved checkpoint and applies matching events to projections. Checkpoints track the last processed position, and projections can be rebuilt from scratch by resetting the checkpoint.

For read-your-writes scenarios, poll the projection version until it reaches the expected event version before executing the query, with a timeout fallback. Define acceptable lag SLAs and return stale data with a warning when the timeout expires.

Avoid CQRS for simple CRUD applications where read and write needs are identical, since it adds event handling, projection, and consistency complexity. Start simple and adopt CQRS only when read/write scaling or modeling requirements genuinely diverge.