bytelyst/learning_ai_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
131b73cfc1
learning_ai_notes/docs/MOBILE_SYNC_DECISION.md

2.4 KiB
Raw Blame History

Mobile Sync Decision

Status: active decision Date: May 5, 2026 Decision: defer @bytelyst/sync adoption for the production-readiness handoff.

Context

NoteLett mobile currently uses:

  • REST hydration through mobile/src/api/*
  • Zustand stores for notes, workspaces, prompts, inbox, and auth
  • @bytelyst/offline-queue in mobile/src/lib/offline-queue.ts for failed note create/update retries
  • auth-gated queue flushing from mobile/src/app/_layout.tsx

The shared @bytelyst/sync package provides an offline-first sync engine with entity mapping, persistent queue storage, pull/push cycles, conflict handling, retries, reconnect flushing, telemetry hooks, and configurable storage.

Decision

Defer replacing the current mobile offline queue with @bytelyst/sync until NoteLett has explicit backend contracts for entity-level sync and conflict resolution.

The current queue is intentionally narrow: it retries note create/update mutations after transient failures while keeping reads as live REST hydration. That is suitable for the current handoff. Moving to @bytelyst/sync would require product decisions about stale reads, workspace membership changes, note version conflicts, agent-action review state, prompt/intake jobs, and blob-backed artifacts.

Required Adoption Criteria

Adopt @bytelyst/sync later when these are defined and tested:

  • entity map for notes, workspaces, relationships, tasks, artifacts, prompts, intake jobs, and agent actions
  • backend endpoints that support pull windows, updated-since cursors, tombstones, and conflict responses
  • conflict strategy for note title/body edits versus server-side versions and agent proposals
  • product-scoped storage keys using PRODUCT_ID
  • MMKV storage adapter parity and migration from the current offline queue key
  • telemetry events for sync success, failure, conflict, queue depth, and retry exhaustion
  • UX for sync status, stale data, retry failures, and conflict review
  • tests proving parity with current note create/update offline behavior before removing @bytelyst/offline-queue

Current Guardrails

  • Keep @bytelyst/offline-queue as the mobile mutation retry foundation for this handoff.
  • Do not add a second queue that can replay the same note mutation twice.
  • Expand the current queue only where production-readiness P6/P7 require clear retry UX.
  • Revisit @bytelyst/sync after backend sync contracts and mobile offline acceptance tests are explicit.