Event Types

A domain event is a record that something meaningful happened in the domain model of one bounded context, expressed in that context's ubiquitous language, such as OrderPlaced or LineItemRepriced. It is usually raised by an aggregate when a state change succeeds, for example through Spring Data's AbstractAggregateRoot.registerEvent, and published when the repository saves the aggregate. Its consumers are handlers in the same context or modular monolith, which react after commit using @TransactionalEventListener or Spring Modulith's @ApplicationModuleListener. Because it is private, it can use internal value objects and enums, be fine-grained and change whenever the model changes. That freedom is exactly why it should not be published directly to other teams.

A notification event is a thin signal that something changed, carrying only the event type, an identifier and perhaps a link, not the changed state. A CloudEvents message of type shopnow.product.changed with subject sku/SKU-4411 is typical. Consumers that care call back to the source's API to fetch the current data, so they always see the latest state and the producer's authorisation rules apply on every read. This is Fowler's event notification pattern. It suits external partners through signed webhooks, large or sensitive payloads such as customer addresses, and data that changes often. The cost is runtime coupling: consumers depend on the producer's API being available and fast.

Because a domain event is part of your internal model, so publishing it turns your internal model into a public contract. Domain events use internal value objects, enums and names that change whenever the team refactors. Once other teams consume them, every rename or restructuring becomes a breaking change that needs coordination, so your context loses its freedom to evolve. Domain events are also fine-grained and may expose fields others should not see. The note's example: order-svc serialised its JPA entity to Kafka, and renaming one enum broke four consumer teams. The fix is to translate domain events at the boundary into curated, versioned integration events, such as OrderPlacedV1, using primitive and standard types.

An integration event is a contract because other contexts build on it, so the publisher promises stability. It is curated: only the fields consumers need, in agreed business vocabulary and portable types, for example totalPaise and currency instead of an internal Money object. It has an explicit schema in a schema registry such as Confluent or AWS Glue, with compatibility rules, usually backward compatibility, enforced on every change. It is versioned, with names like OrderPlacedV1 and topic orders.events.v1, and a breaking change creates a new version while the old one runs in parallel. It is documented in AsyncAPI with an owner, and reviewed like a public API before release.

Notification events are a poor choice when many consumers would call back for the same data, when the producer's availability is a concern, or when consumers need the history of changes. Each notification triggers a call per consumer, so twelve consumers and 3,500 events a minute produce 42,000 API calls, a call-back storm that can overload the producer at peak. Every consumer also depends at runtime on the producer's API, so its outage stops all of them. Because notifications are thin, a consumer that misses intermediate states cannot reconstruct what happened. In those cases event-carried state transfer, integration events with the needed state, is usually better, accepting larger payloads and eventual consistency.

The key is to make publishing part of the same transaction as the state change, then deliver asynchronously. The aggregate raises a domain event, and a translator listens after commit and maps it to an integration event. With Spring Modulith, the event publication registry stores each publication in the database within the business transaction, and @Externalized routes the integration event to a Kafka topic with a key, so incomplete publications are retried after a restart. Without Modulith, the transactional outbox pattern does the same: write the event to an outbox table in the same transaction, then relay it with a poller or Debezium. Consumers must still be idempotent, because delivery is at least once.

Give analytics a different contract instead of bloating integration events. Integration events are deliberately curated for operational consumers; adding every column to satisfy the data platform would expose internals, make the schema change constantly and couple every consumer to those changes. For analytics that need every field and full history, a change data capture stream from the database, using Debezium or AWS DMS into Kafka or a data lake, is usually better, ideally owned as a data product with documented semantics and access controls. Sensitive fields can be masked or tokenised in that pipeline. The operational integration events stay small and stable, and the analytics contract can evolve on its own terms.

I would set a few clear rules and automate their checks. First, a naming convention such as shopnow.order.placed.v1 and one topic per context, keyed for ordering. Second, a rule that entities and domain events never go onto shared topics, enforced in review and with ArchUnit checks that published types live in an api package. Third, integration events are reviewed like public APIs, registered in a schema registry with backward-compatibility checks in CI, and documented in an AsyncAPI catalog with an owner. Fourth, notifications are the default for external partners and sensitive data, signed with HMAC. Finally, regular reviews look for notification storms and over-fine public events.