Architecture Decision Record
A compact, evidence-based decision note: context, options, selected approach, trade-offs, review triggers and accountable approval.
Decision and status
An ADR begins with one specific choice
Local-first durable event outbox
Decision: Each device will persist outbound events in a local durable outbox before attempting synchronization. The central API will deduplicate by event ID and reconcile events using explicit domain rules.
Context and drivers
What problem are we solving?
Field applications must record operator actions while disconnected. A transport-only retry scheme cannot guarantee that an action survives an application restart, and network acknowledgement may be lost after the server has already accepted an event.
- Network interruptions are expected and cannot be treated as exceptional.
- Duplicate delivery is preferable to silent data loss if consumers are idempotent.
- Users must see whether a recorded action is pending, accepted or rejected.
- Conflict resolution is a domain responsibility, not a transport timestamp rule.
Options considered
Show why the decision was made
| Option | Advantage | Cost / risk |
|---|---|---|
| A · Direct API request | Simple online-only path. | Fails to capture reliably during outages; weak restart recovery. |
| B · Local durable outbox | Survives restarts; explicit delivery state; repeatable tests. | Requires storage lifecycle, idempotency and reconciliation logic. |
| C · Peer-to-peer replication | Can share data without central access. | Additional discovery, security and conflict complexity. |
Consequences and trade-offs
State the downside as clearly as the upside
What improves
- Durability during disconnection.
- Visible queue health and delivery status.
- Deterministic replay and incident review.
What must be built
- Local storage migration and pruning.
- Server-side idempotency store.
- Operator conflict and rejection handling.
Verification and review triggers
The decision is only complete when testable
Review this ADR if the requirements change to demand near-instant cross-device consensus, strongly ordered offline writes, or independently authoritative peer nodes.
Decision ownership and history
Keep the final authorization distinct from the author
| Attribute | Value |
|---|---|
| Decision owner | Platform Architect (example role) |
| Prepared by | Carlo Hennsa |
| Reference | EX-ADR-007 |
| Status | Proposed / illustrative |
| Reviewed | Not reviewed |
| Issued | 14 October 2026 |
| Supersedes | None |