Sync & Offline
Your vault works everywhere — even without signal.
Offline-First Design
BoxOwl is built around an offline-first architecture. Your vault lives on your device first, and the cloud is treated as a sync target, not the primary source. This means:
- You can read, create, edit, and delete vault items without an internet connection.
- The app launches instantly because it does not wait for a server response.
- Your data is accessible in airplane mode, in basements, or anywhere with poor coverage.
All local data is stored in an encrypted SQLite database using SQLCipher 4.5.4 with 256-bit AES transparent encryption. The encryption key is derived from your credentials and never leaves your device.
Delta Sync
When you are online, BoxOwl syncs only what changed. This is called delta sync. Instead of uploading your entire vault on every connection, the app sends a compact patch containing only the modified fields.
Delta sync reduces bandwidth, preserves battery, and completes in seconds even on slow connections. The sync payload is compressed and sent over TLS 1.3.
Sync Queue
Changes made while offline are placed in a local sync queue. Each entry records:
- The operation type (create, update, delete)
- The affected category and item ID
- A client-side timestamp
- The full payload (for create/update) or a deletion marker
When connectivity returns, the queue is drained in order. If a sync attempt fails (e.g., server error or timeout), the entry stays in the queue and is retried automatically.
You can view the number of pending changes on The Perch. If the count seems stuck, use Pull-to-Refresh or go to Settings > Sync > Force Sync Now.
Conflict Resolution
If you edit the same item on two devices before either syncs, a conflict can occur. BoxOwl resolves conflicts using last-write-wins based on the server timestamp:
- The server compares the timestamps of the conflicting writes.
- The newer write survives; the older write is overwritten.
- No merge dialog interrupts you. The resolution happens silently in the background.
If you need to preserve both versions, the recommended approach is to export your vault as JSON before making large edits on a second device.
Automatic Background Sync
BoxOwl attempts to sync automatically in the background every 15 minutes while the app is open. It also syncs immediately when:
- You pull-to-refresh on The Perch
- You tap Force Sync Now in Settings
- The app detects that the device has reconnected to the internet
- You switch from the background back to the foreground
Manual Sync Controls
Go to Settings > Sync to access manual controls:
| Control | What It Does |
|---|---|
| Force Sync Now | Immediately pushes pending changes and pulls the latest server state |
| Last Synced | Shows the timestamp of the most recent successful sync |
| Pending Changes | Shows the number of operations waiting to be sent |
| Sync on Wi-Fi Only | When enabled, prevents sync over mobile data |
What If Sync Keeps Failing?
If you see a persistent "Sync failed" message in the activity feed:
- Check your internet connection.
- Verify that your JWT session has not expired (log out and log back in if needed).
- Try Force Sync Now from Settings.
- If the problem persists for more than 24 hours, export your vault as a JSON backup and contact support.
Your local data is safe regardless of sync status. Nothing is lost if the server is temporarily unreachable.