domainsevents

Domain events are facts that something meaningful has occurred within a domain model. In domain-driven design and event-driven architectures, a domain event records a state change of an aggregate or entity and is used to communicate that change to other parts of the system. A domain event is immutable once created. It carries identifying information and relevant attributes needed by consumers to react or reconstruct state, such as entity IDs, timestamps, and necessary payload.

Domain events are typically produced by aggregates after a successful operation, and may be persisted in an event store (in event-sourced systems) or published to a message bus for asynchronous processing. They enable eventual consistency across bounded contexts, integration with external systems, and auditing.

Distinguish between domain events and integration events or commands. Domain events model facts within the domain; integration events are designed for communication between bounded contexts or external services; commands are requests for action that may or may not succeed.

Best practices: keep events small and purpose-focused, version payloads, avoid leaking internals, provide stable names, include identifiers and timestamps, make events idempotent where possible; consider idempotency keys.

Example: An Order aggregate publishes an OrderPlaced domain event when an order is created, containing orderId, customerId, totalAmount, currency, and timestamp. Subscribers update inventory, notify customer, and update analytics.