---
name: design-domain-events
description: Discover and design domain events for a new event-driven or event-sourced workflow. Use when defining business processes, commands, decisions, aggregate lifecycles, event payloads, downstream reactions, or a domain event vocabulary before implementation.
---

# Design Domain Events

## Begin with business scenarios

1. Describe a concrete success scenario and its meaningful failure cases.
2. Name the actor's intention as an imperative command.
3. State the information and rules needed to make the decision.
4. Ask what a domain expert would say happened after the decision succeeded.
5. Name that fact in past tense using the ubiquitous language.

Model the fact before choosing a message broker, database schema, class hierarchy, or event envelope.

## Define the event

- Represent an immutable business fact, not a request or implementation step.
- Record why the aggregate changed, not merely which property has a new value.
- Include the cohesive domain data needed to understand and apply the fact later.
- Use value objects when the payload contains concepts with rules or meaning.
- Include identity, time, causation, or actor information only where the domain or audit requirements need it; keep transport metadata in the envelope.

Prefer specific facts such as `OrderPlaced`, `PaymentReceived`, or `AppointmentCancelled`. Avoid starting with generic names such as `Updated`, `Saved`, or `StatusChanged`; return to the business decision and name its outcome.

## Separate facts from reactions

Treat projection updates, notifications, integrations, retries, and persistence as reactions to the event. Model them as domain events only when the business recognizes them as meaningful lifecycle facts.

For each reaction, decide whether it is:

- an immediate state application within the aggregate;
- a projection or read-model update;
- a policy that may issue another command;
- an integration event for another bounded context; or
- a technical side effect handled through infrastructure.

## Validate the vocabulary

Walk through success, rejection, cancellation, repetition, and out-of-order scenarios. Confirm that the event names make sense to domain experts, explain the aggregate's lifecycle, and provide enough information for required consumers without coupling to their internal schemas.

## Deliver

Provide the scenarios, commands, decision rules, domain events, payload rationale, aggregate state application, downstream reactions, and unresolved terminology. Distinguish domain events, integration events, and technical messages explicitly.