Feature: Offline-First Mobile Document Capture and Sync Queue

[hoangsonww]

Summary

Add an offline-first capture and sync workflow to the mobile app so users can import documents, queue analysis requests, and continue lightweight review work when network connectivity is unreliable.

Problem / Opportunity

The mobile app already mirrors core auth, library, summary, chat, and profile flows, but those flows depend on live backend access. Mobile users often capture files while traveling, in meetings, or on unstable connections. DocuThinker should preserve that work locally and sync it once connectivity returns.

Proposed Feature

Implement a mobile sync queue that stores pending uploads and requested analysis actions locally, tracks their state, and reconciles them with the backend when the device is online. The UI should make queued, syncing, failed, and synced states explicit without blocking access to already available local metadata.

Scope

• Mobile document capture/import path that can create local pending records while offline.
• Persistent sync queue using the existing mobile storage conventions, with retry and cancellation controls.
• Connectivity detection and background/foreground reconciliation.
• Backend support for idempotent upload requests or client-generated correlation ids, if the current API cannot safely deduplicate retries.
• Library/profile UI states for pending uploads, failed syncs, retry actions, and conflict messages.
• Documentation for offline limitations, storage behavior, and testing steps.

Acceptance Criteria

• A user can add a document on mobile while offline and see it as a pending item in the library.
• When connectivity returns, queued uploads sync automatically with visible progress and final status.
• Retried uploads do not create duplicate server-side documents when the same queued item is submitted more than once.
• Users can retry or remove failed queued items from the mobile UI.
• Queued analysis requests run after upload completion, or clearly explain why they cannot run offline.
• Tests cover queue persistence, connectivity transitions, duplicate retry prevention, and failure recovery.

Non-Goals

• Full offline AI analysis on device.
• Offline cross-document RAG or vector search.
• A complete redesign of the mobile library screen beyond the states needed for this workflow.

Dependencies / Risks

• Requires careful handling of local file paths and storage cleanup across app restarts.
• May require backend idempotency support for uploads if not already available.
• Needs platform-specific validation on iOS and Android file/document picker behavior.

Open Questions

• How long should pending local files be retained if they never sync?
• Should queued items be encrypted at rest beyond the platform defaults?
• Should users be able to queue multiple analysis actions per document before upload completes?