Backup & Sync

Tsumihon uses Supabase as its cloud backend to keep your library synchronized across all your devices in near real-time. Once configured, changes you make on one device appear on your other devices within seconds.

Cloud Sync via Supabase

Real-time sync is the core of Tsumihon's multi-device experience. When you add, edit, or delete a book on any device, the change is propagated to all your other devices automatically.

• Near-instant propagation — changes typically arrive on other devices within ~10 seconds.
• Conflict-free — the sync system handles concurrent edits gracefully, using timestamps to resolve conflicts.
• Selective sync — metadata syncs automatically; large assets like downloaded pages are managed separately.

Tip: You need a Supabase project to use cloud sync. See the Supabase setup guide for initial configuration.

How Sync Works

The sync pipeline follows a push-notify-pull architecture:

1. Device A makes a change — a book is added, edited, or deleted.
2. Supabase stores the change — the updated record is written to the Supabase database.
3. Database trigger fires an edge function — a Postgres trigger invokes a Supabase Edge Function on write.
4. FCM notification sent to other devices — the edge function sends a Firebase Cloud Messaging push to all other registered devices for the same user.
5. Other devices refresh — upon receiving the FCM message, each device pulls the latest data from Supabase and updates its local cache.

This architecture ensures that devices stay in sync even when the app is in the background, as long as push notifications are enabled.

Background Sync

In addition to real-time push-based sync, Tsumihon runs a periodic background task to catch any changes that may have been missed (e.g., if the device was offline when a push was sent).

• The background sync task runs approximately every 1 hour.
• It is registered via registerPeriodicTask and managed by the OS task scheduler.
• Each run performs a full diff between the local database and the remote Supabase state, pulling any missing changes.

Backup Scheduler

The backup scheduler ensures your library data is periodically written to Supabase, even outside of individual edit operations. It includes several safeguards to prevent excessive writes and race conditions:

• 10-second startup delay — the scheduler waits 10 seconds after app launch before its first run, allowing the app to finish initialization without contention.
• SharedPreferences throttle — a timestamp is stored in SharedPreferences to prevent the scheduler from running more frequently than its configured interval.
• Re-entrancy guard — if a backup is already in progress, subsequent triggers are skipped rather than queued, preventing overlapping writes.

Tip: You do not need to manually trigger backups. The scheduler handles everything automatically once Supabase is configured.

Getting Started

To enable backup and sync, you need to set up a Supabase project and connect it to Tsumihon. Follow the Supabase setup guide for step-by-step instructions on creating your project, configuring authentication, and connecting your app.