Mobile System Architecture and Offline-First Design Questions

Strategies: local search index + periodic sync, server-provided precomputed search bundles, and hybrid incremental sync.

Client-side: maintain a local inverted index (SQLite FTS or Realm) of recently synced articles and metadata. Provide search over local index when offline. Periodically sync deltas.

Server-side patterns:

• Full/partial sync API: /sync?since=<cursor> returns created/updated/deleted items; client applies to local DB.
• Search bundles: /search-bundle?lang=en&scope=home returns compressed index or top results packaged for offline use (e.g., JSON + tokenized terms).
• Lightweight query API for online use; fallback to local index when offline.

Sync considerations: send minimal deltas (change sets), include cursors and sequence numbers, support resumable downloads and integrity checks. Use background sync and conflict-free merges. This enables responsive offline search while minimizing bandwidth.

Requirements & constraints:

• Create/edit/delete notes offline, low-latency UX, sync bi-directional when online, handle conflicts, minimal data usage, secure, scalable.

Client-side design:

• Storage: SQLite (or Realm) as authoritative local store + a write-ahead change log (operations queue) with monotonic client Lamport timestamp or logical counter and a UUID per note.
• Data model: Note {id: UUID, content, title, updated_at: client_ts, tombstone: bool, version: int}
• Sync metadata: last_synced_server_version, pending_ops queue.
• Sync flow: periodic/connection-triggered push-pull:
  1. Push: send batched pending_ops to server (idempotent, include client_id, op_id, client_ts).
  2. Pull: request server deltas since last_synced_server_version.

Conflict resolution strategies:

• Last-Writer-Wins (LWW): Compare timestamps (server_ts or logical counter). Simple, efficient. Con: may lose edits.
• CRDTs (e.g., RGA or Sequence CRDT for text): Converges without central resolution; handles concurrent edits with minimal user friction. More complex and larger payloads.
• User-merge: Detect conflicts (concurrent edits on same note) and surface a merge UI showing both versions; good UX for critical notes.
  Recommendation: Start with LWW + per-field timestamps (preserve last edit per field) and tombstones; for collaborative editing or heavy concurrent editing, adopt CRDTs for content and combine with user-merge for semantic conflicts.

API design (REST-ish JSON with idempotency):

• POST /sync/push
  body: {client_id, ops: [{op_id, op_type: create|update|delete, note_id, payload, client_ts}]}
  returns: {accepted_ops: [...], rejected_ops: [...], server_version}
• GET /sync/pull?since=server_version
  returns: {ops: [...], server_version}
• GET /notes/{id}
• Optionally WebSocket /push-notify for real-time updates.

Server-side model & scalability:

• Authoritative store: Notes table with note_id, owner_id, content, metadata, version (monotonic server counter), tombstone flag.
• Apply ops idempotently: track processed op_ids per client to avoid duplicates.
• Conflict handling: Apply LWW using (server_version, client_ts) tie-breaker; or apply CRDT merge if used.
• Scale:
  • Horizontal stateless sync service fronted by API gateway/load balancer.
  • Shard notes by user_id (hash) across DB clusters. Use consistent hashing.
  • Use write-optimized DB (Cassandra, DynamoDB) for high write throughput; store history in append-only store for audit.
  • Background workers for heavy merges, analytics.
  • Cache recent server_versions per user in Redis for fast pull responses.
• Storage compaction: periodically compact tombstones and CRDT metadata.
• Security: TLS, auth tokens, per-device keys; encrypt content at rest if needed.

Trade-offs:

• LWW simpler and lower cost; CRDT provides correctness for real-time collaboration at complexity/cost.
• Batched ops reduce network cost but increase conflict window.
• User-merge best UX when automatic resolution could cause data loss.

Edge cases:

• Clock skew: prefer logical counters or server-assigned monotonic version to avoid relying on client clocks.
• Large notes: chunk sync or delta sync (operational transforms/CRDT deltas).
• Offline deletes vs recreate: use tombstones with retention policy.

This design balances quick implementation (LWW + ops queue) with a clear upgrade path to CRDTs and user-merge for stronger conflict semantics and scalability.

Requirements:

• Offline-first for 5M users, batched uploads when online, conflict resolution, energy-aware scheduling, reasonable latency and scalability.

High-level architecture:

• Clients maintain local DB + operation log (oplog). Server exposes sync APIs and an authoritative per-entity state store with versioning (vector clocks / causal metadata). A sync gateway (stateless) handles auth, rate limiting, and routes to sync workers that apply ops and run conflict resolution. Persistent queue (Kafka) for downstream processing and analytics.

Client data model (oplog vs state merge):

• Use oplog as primary local model: record user intents (create/update/delete) as immutable operations with timestamps and client ID, causal metadata and a per-client monotonically increasing sequence. Apply ops locally to a derived state for immediate UI responsiveness (optimistic). Keep tombstones for deletes.
• Periodic compaction: convert oplog into checkpointed state to bound storage.

Server APIs:

• POST /sync/push {client_id, last_sync_seq, ops[]}
• GET /sync/pull?since=server_seq&client_id=...
• POST /sync/ack {client_id, ack_seq}
• GET /entity/{id}?v=...
  APIs are idempotent, accept batched ops and return per-op result + conflict hints.

Conflict resolution strategy:

• Prefer CRDTs where data type permits (counters, sets, registers) for automatic, safe merges.
• For complex documents: hybrid approach — server tries deterministic merge using operational transforms or per-field CRDTs; fallback to last-writer-wins using vector clocks for simple fields where LWW is acceptable.
• Expose manual merge for user-visible conflicts: create a conflict record, notify client UI with both versions and metadata; allow user to resolve which produces a final op applied to server and propagated to other clients.

Energy-aware scheduling & batching:

• Defer syncs to energy-friendly windows: when device is charging, on Wi‑Fi, or meets a backoff schedule. Use OS job schedulers (WorkManager on Android, BGTasks on iOS) to batch network use.
• Adaptive backoff: short aggressive retries while app foreground; otherwise exponential backoff. Bundle operations into payloads up to reasonable size and compress diffs (protobuf/gzip).
• Network-awareness: avoid background sync on cellular unless user opted-in; use low-power radios scheduling.
• Prioritize critical ops (payments) for immediate sync; low-priority ops wait for batch windows.

Scalability & robustness:

• Shard server state by user ID; use causal vectors truncated via dotted-versioning to limit metadata size. Use background reconciliation jobs to garbage collect tombstones after safe windows.
• Monitor conflict rates; if high, consider schema or UX changes to reduce simultaneous edits.

Trade-offs:

• Oplog + CRDTs increases client storage and metadata complexity but gives correct merges and offline UX. LWW is simpler but can lose updates.
• Energy-aware delays add eventual consistency latency for non-critical data.

This design balances correctness (CRDTs/explicit merges), scalability (batched APIs, sharding), and low energy impact (OS schedulers, batching, network-awareness).

Compare three strategies for offline writes:

1. Last-Write-Wins (LWW)

• Example: note app where each update has timestamp; latest timestamp wins.
• Pros: simple to implement, low metadata, easy on mobile.
• Cons: data loss for concurrent edits, clock skew issues.
• Complexity: low — include timestamp vector in record and server picks max.

2. Merge rules (application-specific)

• Example: task app: merge by field (title LWW, subtasks merged, counters summed).
• Pros: preserves intent, fewer conflicts lost, predictable behavior for domain objects.
• Cons: requires domain logic, more testing, edge cases.
• Complexity: medium — implement merge functions on client and server, run tests for invariants.

3. CRDTs (Conflict-free Replicated Data Types)

• Example: collaborative document or shopping list using RGA or LWW-Element-Set.
• Pros: strong convergence without central conflict resolution, supports concurrent edits naturally.
• Cons: higher metadata overhead, complex implementation, harder to reason about for non-trivial types.
• Complexity: high — requires careful CRDT selection and efficient encoding for mobile; need garbage collection.
  Recommendation: choose based on domain: simple LWW for non-critical single-field data; merge rules for structured objects where intent matters; CRDTs for collaborative multi-user concurrent editing. For mobile, prefer merge rules when feasible (balance complexity vs UX) and reserve CRDTs for heavy collaboration features.

Goals: let mobile clients behave correctly under mixed connectivity and partial syncs.
API-level signals and semantics:

1. Consistency level:

• Response header: X-Consistency: strong|eventual|stale
• Body field: "consistency": {"level":"eventual","asOf":"2025-12-20T12:00:00Z"}
  Server semantics: strong indicates read-your-writes or linearizable for the resource; eventual indicates data may lag and gives asOf timestamp to let client decide.

2. Sync progress for large downloads:

• Use pagination with progress metadata: body {"items": [...], "page": N, "totalPages": M, "progress": {"downloadedBytes": 12345, "totalBytes": 98765}}
• Headers: X-Sync-Page, X-Sync-Total-Pages, X-Sync-Progress: percentage
  Server streams can send periodic checkpoints with resume tokens.

3. Resume tokens:

• Provide opaque resume token in header X-Resume-Token and body field resumeToken. Token encodes server cursor and TTL; clients send it in subsequent requests: GET /sync?resumeToken=abc
• Token semantics: valid for N minutes/hours; server verifies and resumes from cursor; token invalidation leads to full sync.
  Examples:
  Headers:
  X-Consistency: eventual; X-Resume-Token: abc123; X-Sync-Progress: 42
  Body snippet:
  {"consistency":{"level":"eventual","asOf":"..."},"items":[...],"resumeToken":"abc123","progress":{"downloaded":42,"total":100}}
  Why: explicit headers + body give clients quick routing decisions; opaque tokens avoid client coupling to internal cursors while enabling efficient resumption.