Four lines from a Monday log
A veterinary clinic's booking system, a little before nine on a Monday:
08:47:12 appointment 5521: cancel (Biscuit, Dr Okafor, Thu 14:30)08:47:12 sms to owner of Biscuit: appointment cancelled08:47:12 waitlist: Thu 14:30 with Dr Okafor offered to owner of Pepper08:47:13 ERROR deadlock detected, transaction rolled back
Read from the bottom up, it is a small mess. The cancellation never happened, and the appointment row still says Biscuit, Thursday, 14:30. Yet Biscuit's owner has been told not to come, and Pepper's owner has been offered a slot that still belongs to Biscuit.
The cancel() method on the Appointment class did all of it. It checked that the appointment could still be cancelled, set its status, then called the SMS sender and the waitlist directly, before the transaction had committed. That is two different problems. The appointment knows every part of the clinic that cares about a cancellation, so the next one means editing Appointment again. And the follow-ups ran at the moment of the call, while the change was still only an intention.
A fact, written down by the appointment
A Domain Event is a record of something that happened in the domain and matters to the business, named in the past tense: AppointmentCancelled. The appointment, an Aggregate here (the object that enforces the booking rules), raises it once its rule has passed and its own state has changed; if the rule refuses, because Biscuit has already checked in at reception, nothing changes and no event is raised. It calls nobody. It writes down what happened and leaves the reactions to whoever listens: the SMS sender, the waitlist and next month's preparation list subscribe to the event, and adding one more no longer touches Appointment.
The past tense is part of the idea. CancelAppointment is a request, and requests can be refused; AppointmentCancelled is a fact, and facts can only be reacted to. Naming the event after the request that caused it couples subscribers to a command instead of a domain fact.
What goes in the event
The first version carried only the appointment id. The waitlist handler loaded the appointment to see which slot had opened and found none, because a cancelled appointment no longer holds one. The aggregate keeps changing after the event, so the event has to describe the fact as it was when it happened. AppointmentCancelled now carries:
- the appointment and patient ids, for looking up anything else;
- the slot that was released: Dr Okafor, Thursday 14:30, consulting room 2;
- who cancelled, the owner or the clinic, and a reason code, because a late-cancellation fee depends on the first and the clinic's reports on the second;
- an id of its own and the time it happened.
What stays out matters as much. Not the owner's phone number: the SMS handler looks it up, and a number copied into events goes stale and lands wherever events are logged. Not the whole appointment either, or every listener depends on every field and the appointment can no longer change shape without breaking them. A field belongs if a listener needs it to react to this fact, above all when it could be gone or different by the time the listener runs.
Collected now, handed out after the commit
An event that exists says the change was made, in memory at least; whether it survives is up to the transaction. So the fix for the log separates raising an event from delivering it. Appointment.cancel() appends AppointmentCancelled to a list the appointment keeps, and nothing else happens yet. The application service running the use case takes the collected events when it is done and hands them to an in-process dispatcher, which calls each handler (Application Service (DDD) describes that coordinator). The open question is when. Replay Monday with the events handed out after the commit:
- The application service loads appointment 5521 and calls
cancel(). - The appointment checks that Biscuit has not checked in, sets its status to cancelled and adds
AppointmentCancelledto its list. - The application service saves the appointment and commits.
- The commit hits the deadlock and rolls back, and the collected event is discarded with the rest of the request.
- No text goes out and no slot is offered; the front desk sees an error and tries again.
When the commit succeeds, the application service passes the event on, and both handlers act on a cancellation that is really in the database.
Handing events out before the commit, inside the same transaction, suits a handler that only writes to the same database, such as the table behind the front desk's day view: it commits or rolls back with the cancellation. The price is that a failing handler fails the cancellation too, and an effect outside the database, like the text in the log, cannot be rolled back at all.
After the commit has a gap of its own. If the process dies between the commit and the dispatch (a deploy, an out-of-memory kill), the event existed only in memory and is lost: the appointment is cancelled and nobody hears about it. A handler that fails afterwards cannot undo the cancellation either; it has to retry or be noticed. An empty slot nobody is offered costs the clinic a consultation, so that event is worth storing in the same transaction as the cancellation and delivering from there, which is what a Transactional Outbox does.
Inside the clinic's code, and outside it
All of this happens inside the scheduling module, whose handlers are deployed with it, so AppointmentCancelled can change shape whenever the model does, as long as events already stored for delivery can still be read. The invoicing service, run by another team, should not depend on that shape. Scheduling gives it an integration event instead: a separate message, usually with fewer fields, versioned and kept stable on purpose, published through the broker. Command, Document & Event Messages takes it from there: the kinds of message that cross service boundaries and how to name them.
Ways to get it wrong
- Raising the event apart from the state change. If the application service sets the status and then raises
AppointmentCancelled, another path can change the status without the event: the action the clinic uses when a vet calls in sick cancels that vet's appointments, and the waitlist never hears about those slots. Raised inside the appointment's own method, the event comes with every cancellation, as long as every path cancels through that method. - Hiding business decisions in handlers. A late-cancellation fee buried in a handler is a rule that is easy to miss; Policy (reactive rule) makes it explicit.
- Mistaking the events for the record. Here the row is the truth and events report changes to it; storing the events as the state is Event Sourcing, a different design.
One more handler
The Aggregate & Repository Challenge includes the requirement "Emit a Domain Event from the aggregate". Draw the edge from the aggregate to a Domain Event node with a past-tense title, naming something your aggregate decides, and give each reaction its own Service node, renamed for its job and connected from the event, not from the aggregate. Then try adding one more reaction. If it needs an edge from the aggregate to the new service, the aggregate is still calling its listeners.