Architecture

Model Domain Events for Important State Changes

Represent meaningful business facts as events to coordinate behavior without tightly coupling every component.

A domain event records that something meaningful has happened in the business model. It is not simply a log line or a renamed method call.

Name events as past facts

Examples include OrderPlaced, ArticlePublished, or SubscriptionCancelled. Events should describe completed facts, not commands such as PublishArticle. Commands request work; events report that work has occurred.

Keep event payloads intentional

Include the identifiers and facts consumers need, but avoid copying entire database records or sensitive information. Events may be retained, replayed, or delivered to systems with different access controls.

Distinguish in-process and durable events

An in-process event dispatcher can decouple modules within one request. Reliable asynchronous delivery requires durable storage and retry behavior. The transactional outbox pattern can ensure an event record is committed with the state change it describes.

Handle duplicates and ordering

Consumers should be idempotent because delivery may happen more than once. Include event IDs and, where necessary, aggregate versions. Do not assume global ordering across unrelated entities.

Checklist

  • Use past-tense business facts.
  • Keep payloads small and intentional.
  • Persist events when delivery must be reliable.
  • Make consumers idempotent.
  • Define ordering requirements explicitly.
Share this page Help other developers discover this resource.