Mutation Outbox Service
Component Detail
Description
Serializes pending write operations with retry metadata into a persistent outbox queue stored in the encrypted local DB. Replays mutations in order against the REST API when connectivity is restored, guaranteeing no data loss during offline sessions.
mutation-outbox-service
Sources & reasoning
The mutation outbox is the core reliability mechanism for offline writes. Without it, any write operation performed while offline would be silently dropped. Given HLF peer mentors logging 380+ activities per year in variable-connectivity environments, silent data loss is operationally unacceptable and would corrupt Bufdir reporting.
No source references — this artifact was included based on reasoning alone (see above).
Responsibilities
- Enqueue local mutations (create, update, delete) with serialized payloads and retry counters
- Persist outbox entries across app restarts using the encrypted Drift database
- Replay queued mutations against the REST API in order when online
- Emit sync-state events so UI layers can display pending/synced indicators
- Coordinate with ID Mapping Service to rewrite local IDs before replay
Interfaces
enqueue(mutation: OutboxMutation): Future<void>
replayPending(): Future<SyncResult>
getPendingCount(): Stream<int>
clearSynced(): Future<void>
retryFailed(): Future<void>
Relationships
Dependencies (2)
Components this component depends on
Dependents (3)
Components that depend on this component
Related Data Entities (12)
Data entities managed by this component