The Outbox and Reconciliation

Atomic dual-write via an outbox, at-least-once delivery, and books reconciled against the outside world

The Outbox and Reconciliation Atomic dual-write via an outbox, at-least-once delivery, and books reconciled against the outside world 01 / Source of truth 02 / Relay 03 / Delivery 04 / Reconcile DB Transaction · state + outbox row · 01 / Source of truth · atomic write DB Transaction state + outbox row atomic write Relay Poller · reads outbox · 02 / Relay Relay Poller reads outbox Message Broker · at-least-once · 03 / Delivery Message Broker at-least-once Idempotent Consumer · dedupes by id · 04 / Reconcile · safe on retry Idempotent Consumer dedupes by id safe on retry Ledger · vs external statement · 01 / Source of truth · two sources Ledger vs external statement two sources Matcher · classifies breaks · 02 / Relay Matcher classifies breaks Auto-resolve · or escalate to human · 03 / Delivery Auto-resolve or escalate to human outbox rows committed publish at-least-once deliver may duplicate compare ledger vs statement breaks missing / mismatch / duplicate Legend primary data policy / PII async batch data store

The Dual-Write Problem

  • • You cannot atomically write to a DB and a broker
  • • The outbox row commits inside the same transaction as the state change
  • • One atomic write, no lost or phantom events

At-Least-Once Delivery

  • • A relay polls the outbox and publishes downstream
  • • The broker may deliver the same message more than once
  • • Consumers must be idempotent to stay correct on retry

Reconciliation

  • • Match the internal ledger against an external statement
  • • Classify breaks: missing, amount mismatch, duplicate
  • • Auto-resolve what you can, escalate the rest to a human

Data-flow diagram • Built with Archify • Create yours ↗ • Hover to trace • R route • Click to focus • +/− zoom • M radar • T theme • E export