Skip to content

ADR-0025: Domain events through a transactional outbox

  • Status: Accepted
  • Date: 2026-11-13

Automation rules, sequences, the first SMS after an application and several notifications react to things that happen in other modules: an application is created, a candidate changes stage, an interview is scheduled, a document is signed. The reaction must not be lost when a process stops right after a commit, and must not happen for a change that was rolled back.

How does one module tell the others that something happened?

  • An event exists if and only if the change it describes was committed.
  • The module that emits does not know who reacts.
  • A consumer that fails is retried without repeating the others.
  • The delivery obeys the isolation between companies.
  1. An outbox table: the event is a row inserted in the transaction of the emitter, and a dispatcher delivers it afterwards.
  2. Publishing to the Redis queue from the request, after the commit. Obvious alternative, listed for comparison: a stop between the commit and the publication loses the event.

Chosen option: 1.

domain_events is the outbox, partitioned by month. An emitter calls emit inside its transaction, with a type from a typed catalog. The body is a JSON object of at most 8 KB. The dispatcher runs in the worker in two lanes, priority (new applications, for the first SMS) and default. A pass finds the companies with pending events (ADR-0006) and, inside each company, reads the events in order of time, queues one job per registered consumer and marks the event as dispatched in the same transaction.

Delivery is at least once: a stop between queuing and the commit delivers again, so every consumer is idempotent by the key of the delivery. A consumer that fails is retried up to 8 times with a doubling wait that starts at 5 seconds. After that the failure is recorded in domain_event_failures. An event emitted by an automation action carries a chain depth. The automation engine stops running rules at a depth of 3 (CHAIN_LIMIT in apps/api/src/modules/platform-automations/automation.types.ts), which keeps rules from triggering each other without end; a constraint of the table caps the stored depth at 10.

The automation engine is one consumer among others.

  • Good, because no event is lost and none describes a change that did not happen.
  • Good, because a new reaction is a new consumer: the emitting module does not change.
  • Bad, because every consumer has to be written to tolerate the same event twice.
  • Bad, because strict order between events is not guaranteed: an event from a long transaction can be committed after a newer one was already dispatched.
  • Bad, because reactions are not immediate. The dispatcher measures its lag against a goal of 5 seconds at the 95th percentile.
  • Bad, because an event pending for more than 35 days is no longer picked up. The daily maintenance routine reports events in that state.
  • apps/api/src/core/events/emit.ts and catalog.ts: emitting, and the catalog of event types.
  • apps/api/src/core/events/dispatcher.ts, delivery.ts and consumers.ts: dispatch, retries and the registry of consumers.
  • apps/api/src/core/events/maintenance.ts: the daily routine.
  • packages/db/migrations/0037_wave03_automation_security.sql: the table.
  • apps/api/test/domain-events.test.ts: the tests.
  • Concept page: Background work. Runtime view shows the sequence from a lead to the first SMS.