43 lines
2.4 KiB
Markdown
43 lines
2.4 KiB
Markdown
# 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.
|