Epic: Real-Time Collaboration & Cross-Device Sync (CRDT + Firebase)

[hoangsonww]

Summary

Add live multi-user editing and offline-first cloud sync to StickyNotes across Web + Mobile.
Use a CRDT (e.g., Y.js) for conflict-free merges, Firebase Auth for identity, Firestore for metadata/permissions, and IndexedDB + Service Worker for offline queueing and background sync.

Why

• Current notes are single-user/local-first; collaboration is a top requested “Future Enhancement”.
• CRDTs remove merge conflicts across micro-frontends (React/Vue) and the Cordova app.
• Proper rules + roles enable safe sharing (owner/editor/viewer) without data leaks.

Scope

Web (React/Vue micro-frontends)

• Replace note editor content with a Y.js document (Markdown friendly).
• Presence: show active collaborators, cursors, and “typing” badges.
• Offline support: cache CRDT updates in IndexedDB; auto-reconcile on reconnect.
• UI for Share (email or link), role selector (owner/editor/viewer), revoke access.

Backend/Middleware

• Lightweight y-websocket (or y-webrtc) provider; deploy behind existing middleware.
• Firestore collections: users, notes, noteShares, noteEvents (audit trail).
• Server clock & TTL to expire stale share links.

Mobile (Cordova/React Native)

• Same Y.js doc; use y-indexeddb (or SQLite) adapter for offline.
• Background sync on resume / connectivity change.

Security

• Firebase Auth for identity; Firestore rules to enforce owner/editor/viewer.
• Signed share links (one-time tokens), optional password on link.
• PII minimization; export data stays local unless user confirms.

Acceptance Criteria

• ✅ Two users can edit the same note concurrently; changes converge with no data loss.
• ✅ Works offline: edits made while disconnected sync on reconnect.
• ✅ Presence indicators visible within < 2s.
• ✅ Share via link/email with owner/editor/viewer roles; revocation applies within 1 min.
• ✅ Firestore rules prevent unauthorized read/write (tested).
• ✅ Import/Export still works (CRDT doc exports to JSON/Markdown).
• ✅ Mobile build syncs the same note with web.
• ✅ Basic audit trail per note (created/edited/shared/revoked).

Technical Notes

• CRDT: Y.js + y-websocket (fallback to y-webrtc if server not available).

• Storage:

  • Firestore: note metadata (title, tags, dueDate, color, pin, shares), not the raw CRDT state.
  • CRDT updates live via WS; snapshot periodically to Firestore (or Cloud Storage) for cold start.
  • IndexedDB for offline queue + local snapshot.

• Rules (sketch):

  match /notes/{noteId} {
    allow read: if isOwner() || isEditor() || isViewer();
    allow write: if isOwner() || isEditor();
  }
  match /noteShares/{shareId} {
    allow read, write: if isOwnerOf(resource.data.noteId);
  }

• Presence: small doc in Firestore/RTDB per note: { uid, displayName, color, lastSeenAt }.

• Service Worker: background sync tag stickynotes-sync; retry with exponential backoff.

Migration Plan

1. Add metadata collections & rules → 2) Deploy y-websocket service → 3) Gate new editor behind feature flag → 4) Migrate existing notes to CRDT snapshots on first open → 5) Enable sharing UI → 6) Roll out to mobile.

Tasks

• Set up Firestore collections & security rules + tests.
• Add y-websocket server (Dockerfile + k8s/compose manifest).
• Integrate Y.js editor in web (React/Vue micro-frontends).
• IndexedDB adapter + Service Worker background sync.
• Presence UI (avatars, cursors, typing).
• Share modal (invite by email/link, roles, revoke).
• Periodic CRDT snapshotting to Firestore/Storage.
• Mobile integration (Cordova): Y.js + offline store; connectivity listeners.
• Audit trail (noteEvents) + minimal viewer.
• Docs: docs/collab-sync.md (architecture, env vars, runbook).
• QA: offline/airplane mode, merge storms, link revoke, e2e latency.