Building the Query Side: Projections

A read model is a plain JPA entity — nothing about it needs to know anything about aggregates, event sourcing, or Axon at all. It's shaped purely for how the data needs to be read back, which often means it's simpler than the aggregate that produces the events feeding it, since it doesn't need to carry any fields that exist only for internal business-rule checks.

This table is genuinely separate from anything on the write side. It has no direct relationship to the event store at all — no foreign key back to it, no shared schema. It's an ordinary, disposable table that could be deleted entirely and perfectly rebuilt by replaying every past event through the same projection that normally keeps it updated live. It exists purely to make reads fast, and nothing else in the system should ever treat it as the "real" source of truth — the event store still holds that role, permanently.

That disposability is a genuine feature, not a limitation. It means a read model's shape can evolve — adding a new indexed column, splitting one table into two for a new query pattern — by rebuilding it from history, rather than needing a careful, risky migration of "live" data the way a traditional CRUD table would.

@Entity
public class CustomerReadModel {
    @Id
    private String customerId;
    private String name;
    private String email;

    public String getCustomerId() { return customerId; }
    public void setCustomerId(String customerId) { this.customerId = customerId; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

A projection is really just a normal Spring component with two jobs, both handled by the same class. It reacts to events by updating rows in the read model table, using @EventHandler methods — notice this is a different annotation from an aggregate's @EventSourcingHandler, because a projection isn't rebuilding anything from a replay; it's just reacting to events as they arrive. And it answers queries by reading straight from that same table, using @QueryHandler methods, with no event replay or aggregate loading involved at all.

On the API side, a controller never talks to CustomerAggregate directly for a read. It goes through the QueryGateway, dispatching a FindCustomerQuery, which Axon routes to the matching @QueryHandler — here, straight to the projection's own fast database lookup. This is CQRS's core promise, now genuinely working end to end: writes and reads are fully decoupled, with reads staying fast and simple regardless of how much validation or event-replaying complexity lives on the write side.

@Component
public class CustomerProjection {

    private final CustomerReadModelRepository repository;

    public CustomerProjection(CustomerReadModelRepository repository) {
        this.repository = repository;
    }

    @EventHandler
    public void on(CustomerCreatedEvent event) {
        CustomerReadModel readModel = new CustomerReadModel();
        readModel.setCustomerId(event.getCustomerId());
        readModel.setName(event.getName());
        readModel.setEmail(event.getEmail());
        repository.save(readModel);
    }

    @EventHandler
    public void on(CustomerUpdatedEvent event) {
        CustomerReadModel readModel = repository.findById(event.getCustomerId()).orElseThrow();
        readModel.setName(event.getName());
        readModel.setEmail(event.getEmail());
        repository.save(readModel);
    }

    @EventHandler
    public void on(CustomerDeletedEvent event) {
        repository.deleteById(event.getCustomerId());
    }

    @QueryHandler
    public CustomerReadModel handle(FindCustomerQuery query) {
        return repository.findById(query.getCustomerId())
            .orElseThrow(() -> new CustomerNotFoundException(query.getCustomerId()));
    }
}

@RestController
public class CustomerQueryController {

    private final QueryGateway queryGateway;

    public CustomerQueryController(QueryGateway queryGateway) {
        this.queryGateway = queryGateway;
    }

    @GetMapping("/customers/{id}")
    public CompletableFuture<CustomerReadModel> getCustomer(@PathVariable String id) {
        return queryGateway.query(new FindCustomerQuery(id), CustomerReadModel.class);
    }
}

There is a small, genuinely real gap in time between an aggregate applying an event and a projection's @EventHandler actually reacting to it and updating the read model — for most systems, milliseconds, but never truly zero. If an API immediately tries to read a customer right after creating them, there's a real, if small, chance the projection hasn't finished updating yet, and the read returns stale or missing data. This is precisely what "eventual consistency" concretely means here — not a vague warning in a textbook, but this exact, specific window between a write being accepted and a read reflecting it.

The practical mistake to avoid is designing an API (or setting a team's expectations) as if a write is instantly visible to every subsequent read. A common pattern to handle this well is having the endpoint that issues the original command return enough information for the client to poll or wait briefly before re-reading, rather than assuming an immediate follow-up read will always see the change.

A second common mistake is letting a projection's @EventHandler method silently swallow exceptions. If updating the read model fails partway — say, the customer row doesn't exist yet when an update event arrives out of expected order — that failure should be visible, not hidden, since a silently-failing projection quietly drifts out of sync with the event store it's supposed to mirror, and that drift can go unnoticed for a long time if nothing surfaces it.