Architecture Decision Record: Transactional Outbox and Idempotent Workers
A reference ADR for durable business events, duplicate-safe processing, retry limits and recovery when a database update must trigger asynchronous work.
On this page +
Status: Proposed reference decision. This record describes a design for a business event that must survive application interruption. It does not report a deployed BRIVOX system or promise exactly-once execution.
Context#
The example application commits an approved service request and must notify a downstream worker. Writing to the database and then publishing a message creates a gap: the process can stop between the two operations.
Publishing first creates a different gap if the later database transaction fails. The goal is durable intent and recoverable processing across those interruptions.
Decision#
Write the business change and an outbox event in the same local database transaction. A separate dispatcher reads committed events and delivers them to the worker or broker.
The event carries a stable identifier, event type, schema version, aggregate identity and the minimum required payload. Do not treat a timestamp alone as a complete ordering strategy. If order matters, define the required scope, such as events for one service request, and enforce it deliberately.
AWS documents the transactional outbox pattern as a response to the dual-write problem and notes the need to handle duplicate messages. The remainder of this record describes proposed application-specific controls for the example.
Handle duplicate delivery explicitly#
The dispatcher can stop after delivery but before recording its success. Therefore a later delivery may repeat the same event.
For a local database side effect, the consumer can claim an event identity using a uniqueness constraint and commit the effect in the same transaction. A duplicate claim then becomes a known repeat rather than another business action. The exact transaction and concurrency behavior must be tested.
For an external side effect, a local processed flag is insufficient: the process can stop after the external service acts. Use that service's idempotency mechanism where available and define reconciliation for uncertain outcomes. Do not describe the resulting workflow as universally exactly-once.
Recovery and operational policy#
Retry transient failures with bounded attempts and backoff. Preserve the event identity during retries and operator-driven replay. Failed events need an inspectable queue, a responsible owner and a reason that excludes sensitive payloads.
Measure the age of the oldest unprocessed event, failed attempts and processing lag. Establish retention and cleanup rules so the outbox does not become an unbounded archive.
Proposed verification#
Stop the producer after its transaction commits. Stop the dispatcher after delivery. Deliver an event twice. Process two events concurrently. Simulate an external timeout after the external operation may have succeeded.
For each case, inspect business state and delivery history against the stated invariants. Those tests are required evidence for an implementation; this reference record does not claim they have already passed.
Consequences and related work#
The design adds storage, dispatching and replay responsibilities. It is justified when lost business events are unacceptable and a local transaction can preserve the intended change.
Read the checkout consistency case study or discuss workflow reliability with BRIVOX's custom software team.
