Develop and extend
Concept Available

Domain Events, Outbox, and Delivery

PostgreSQL is authoritative for event intent and handler delivery state. Dramatiq and Redis provide low-latency at-least-once transport, while handlers own idempotency and the processor owns delivery lifecycle transitions.

For
Backend and platform engineers
On this page
  1. Event model
  2. Atomic production
  3. Delivery lifecycle
  4. Handler contract
  5. Scopes, privacy, and audit
01

Event model

A Domain Event is an immutable typed business fact at Organization or Platform scope. An Outbox Message is its immutable persistence record. One mutable Event Delivery is created for each registered handler. Runtime Telemetry and Security Audit projections remain separate concepts.

02

Atomic production

A domain-specific repository owns one session and one commit for business state, the Outbox Message, and intended Event Deliveries. Event names and schema versions are registered in code. Payloads must be bounded, secret-safe JSON and tenant references must agree with the Event Scope.

03

Delivery lifecycle

Deliveries move through PENDING, ENQUEUED, PROCESSING, and then SUCCEEDED or DEAD_LETTERED. Immediate enqueue happens after commit and is best effort. Reconciliation republishes eligible pending or stale deliveries, never succeeded or dead-lettered work.

04

Handler contract

Dramatiq messages carry only a Delivery ID and safe diagnostics. Workers reload PostgreSQL state, claim atomically, and invoke a statically registered handler. Handler names are durable contracts. Every handler must be idempotent because a crash can occur after its side effect commits but before delivery success is recorded.

05

Scopes, privacy, and audit

Organization events require exactly one Organization; Platform events prohibit one and cannot reference tenant resources. Selected events project to deletion-independent Security Audit Records keyed by Event ID. Monitor responses expose bounded operational metadata and curated display strings, never raw envelope identities or the full payload.

Documentation