Offline-First & Data Sync Engine

Optimistic Local Writes#

Every user interaction—saving links, editing notes, toggling favorites, archiving, or organizing into collections—is applied locally first:

• Zero Blocking: The UI never blocks on HTTP requests or waits for Supabase acknowledgments.
• Immediate State Consistency: If the user closes the app immediately after saving an item, the item remains safely persisted in SQLite.

Sync Lifecycle & Queue#

The background sync manager operates as a reactive state machine:

1. Change Tracking: Any local modification increments an internal revision timestamp and flags the entity for sync.
2. Online Detection: Connectivity listeners monitor network changes using native OS APIs.
3. Batch Push: When online, un-synced items are batched and sent via Supabase REST RPC endpoints.
4. Real-Time Subscription: A Supabase Realtime channel listens for PostgreSQL INSERT, UPDATE, and DELETE events on the user's partition and merges them into the local SQLite store.

Conflict Resolution#

LaterBox utilizes Last-Write-Wins (LWW) with field-level merging based on UTC server timestamps:

• If an item was edited on mobile while offline and edited on desktop concurrently, the newer update timestamp takes precedence.
• Deleted items generate a soft tombstone record that propagates across devices to prevent resurfacing deleted items during sync cycles.