Skip to content

sync-system.md

Latest commit

 

History

History
60 lines (41 loc) · 1.64 KB

sync-system.md

File metadata and controls

60 lines (41 loc) · 1.64 KB
Raw

Sync System

Current Source Of Truth

Isotope uses a local-first browser workspace and Supabase Storage backups.

Canonical backup writes now go to:

  • {userId}/backups/latest.json
  • {userId}/backups/history/{timestamp}-{hash}.json
  • {userId}/cloud-snapshot/latest.json

Legacy read-compatible paths:

  • {userId}/imports/latest.json
  • {userId}/exports/latest.json
  • {userId}/cloud-snapshot/latest.json
  • timestamped files under imports/, exports/, and cloud-snapshot/history/

Safety Rule

A local empty workspace must not overwrite a richer cloud backup.

The server checks best cloud backup candidates before uploads. If local data is empty and a rich backup exists, endpoints return:

{
  "ok": false,
  "code": "BLOCKED_EMPTY_OVERWRITE",
  "message": "Cloud has richer backup. Restore first."
}

Browser Restore

The browser adapter is public/sync/local-data-adapter.js.

It writes:

  • IndexedDB database isotope_main
  • localStorage fallback keys such as isotope_tasks_v2, isotope_sessions_v2, isotope_subjects_v2
  • restore metadata in isotope_restore_metadata

After restore it dispatches isotope:sync_refresh.

Manual Sync Flow

  1. Check auth.
  2. Build local backup.
  3. Count local data.
  4. Call /__auth/backup/best.
  5. If local is empty and cloud is rich, call /__auth/restore-best-backup.
  6. Apply backup to browser local data.
  7. Verify restored counts are non-empty.
  8. Upload canonical backup.

Remaining Limitations

  • sync_items exists as schema but is not yet the runtime queue for every local change.
  • Full UI browser automation proof requires a test login/session and browser automation dependency.