cqrs-implementation

Define separate command and query classes, register handlers in command and query buses, and expose them through FastAPI endpoints. POST, PUT, and DELETE routes dispatch commands while GET routes dispatch queries against a denormalized read model.

A command bus routes state-changing intents to command handlers that validate and persist events, while a query bus routes read requests to handlers that fetch data from optimized read models. Keeping them separate lets each side scale and evolve independently.

Use a read model synchronizer that polls the event store from a saved checkpoint and applies matching events to projections. Checkpoints are saved after each event, and projections can be rebuilt from scratch by resetting the checkpoint to zero.

Use a consistency-aware query handler that checks the projection version against the expected event version before returning data, retrying within a timeout. If the timeout expires, return the stale data with a warning flag.

Avoid CQRS for simple CRUD applications where read and write needs are identical, since it adds event stores, projections, and consistency management overhead. Start simple and adopt CQRS only when read and write scaling or modeling needs genuinely diverge.