Domain Event

Overview

A domain event states a fact: it already happened and cannot be undone. Names use past tense and business language, for example InvoicePaid rather than UpdateInvoiceStatus. Events differ from commands, which ask for something to happen and may be rejected.

How it works

The aggregate raises an event while enforcing its rules. The application layer saves the aggregate and then dispatches the collected events.

class Order:
    def place(self):
        self.status = "PLACED"
        self.events.append(OrderPlaced(self.id, self.total))

# after commit
for e in order.pull_events():
    bus.publish(e)

Order.place() -> OrderPlaced -> [Email handler]
                             -> [Inventory handler]
                             -> [Outbox -> Broker -> other contexts]

Reliable delivery to other services needs the transactional outbox: write the event into an outbox table in the same transaction as the state change, then a relay publishes it.

Pitfalls

• Dispatching before commit, so handlers see state that later rolls back.
• Putting too little data in events, forcing consumers to call back; or too much, leaking the internal model.
• Non-idempotent handlers under at-least-once delivery.
• Changing event shape without versioning.
• Using events for in-process logic that needs a synchronous answer.

Key takeaways

• Events are immutable facts in past tense.
• Dispatch only after a successful commit, using an outbox for reliability.
• Handlers must be idempotent.
• Version event schemas from day one.