Mobile System Architecture and Offline-First Design Questions

Approach summary

• Use an operation-based hybrid CRDT + server reconciliation. Model each item (folder/note) as an object with immutable id (UUID), mutable attributes: name, content, parent_id. Operations are: EditContent(op), Rename(op), Move(op), Create(op), Delete(op). Each op carries (actor_id, lamport_ts, op_id, causal_deps). Edits use CRDT text (RGA/Automerge-style) for intra-item concurrent edits; Rename/Move use operation arbitration with deterministic tie-breakers and structural validation.

Preserve structural invariants

• Always validate parent links to prevent cycles:
  • When applying Move(item, new_parent), check ancestry: traverse parent_id chain (using local/known snapshot) to ensure new_parent is not a descendant of item. If it would create a cycle, reject/transform op.
  • If ancestry is ambiguous due to concurrent moves, server computes canonical DAG using op causal order + deterministic tie-breaker (actor_id, op_id). If conflict creates cycle, server reparent the later op to a safe fallback (root or last-known-valid parent) and emit reconciliation ops to clients.
• Maintain a monotonic "ancestry-version" per item (vector clock or lamport) to assist checks.

Conflict resolution rules

• Content edits: CRDT merge (preserve all concurrent characters/edits).
• Rename: last-writer-wins by (lamport_ts, actor_id); show both names in UI as “Local: X — Other: Y” when concurrent and allow user choose.
• Move vs Move: deterministic winner by (lamport_ts, actor_id). Loser becomes a no-op but client shows inline notification and “Undo/resolve” affordance.
• Move vs Rename/Edit: both can apply; move doesn't lose edits.
• Delete vs other ops: delete wins if causally after ops; if concurrent, keep tombstone + show possible “undelete” if user explicitly restores (server records delete_ts).

Server reconciliation

• Server stores op-log per item and replays respecting causal_deps. Conflicts resolved by rules above. Server emits compacted state + reconciliation ops to clients.
• On detecting cycle after replay, server reparent offending items to computed safe-parent and append reconciliation ops; notify owners with conflict list.

Tombstones and GC

• Use tombstones for deleted items for safe causal reconciliation and to prevent "resurrected" children. Tombstone metadata: deleted_by, delete_ts, keep_children_flag (on delete-with-children semantics).
• GC policy: keep tombstones for retention_window (e.g., 30 days) + until all active clients have acked tombstone via per-client vector clock. Periodic server GC removes tombstones and hard-deletes subtree; emit finalization event.
• For mobile: compact local DB by pruning tombstones older than retention_window or after server ACK to reduce storage.

UX patterns (mobile-focused)

• Immediate local apply + optimistic UI. Show subtle banners when a reconciliation changed local state (e.g., “Moved to X on another device — undo”).
• When lossy automatic resolution occurs (rename or move overwritten), surface a non-blocking conflict card with recommended actions: keep local, keep remote, merge (for names), or manual reposition.
• For concurrent edits conflict (CRDT-synced), show merged document and highlight concurrent regions with “Show other edits” toggle.

Example

• Alice offline renames Folder A -> “Work” (ts=10). Bob offline moves Folder A under Folder B (ts=11). On sync, server orders Bob’s move later; it would not create a cycle → both ops applied. Name chosen by higher ts (Bob’s if he also renamed). If move created a cycle, server reparent Alice’s folder to root and notify.

This strategy balances availability for offline mobile users, deterministic server reconciliation, preserves invariants via ancestry checks, and provides clear, actionable UX for conflicts.

Situation & trade-offs (brief)
Strong consistency (server-side reservation/locks): prevents oversell, simplifies inventory correctness, but adds latency, blocking UX, and higher server coordination; poor for flaky mobile networks and offline. Eventual/optimistic checkout: fast, low-friction UX and supports offline purchase drafts, but risks oversell and complex reconciliation/cancellations.

Hybrid approach (proposal)

1. Fast optimistic checkout on mobile: place a client-side "purchase intent" with a local pending order and show temporary confirmation. Send an asynchronous ReserveRequest to server with cart, device id, payment token. UI shows “Order pending confirmation” and expected time (e.g., ~30s).
2. Short server-side provisional reservation: server attempts to reserve inventory for a short TTL (e.g., 60–300s) when ReserveRequest arrives. If reservation succeeds, confirm immediately. If fails, inform client and offer alternatives (back-order, split shipment, or refund).
3. Offline support: allow creating pending orders locally with optimistic payment authorization (hold on card or tokenization). Synchronize when network returns; server applies same reserve-with-TTL logic; if reserve fails, surface clear recovery options.
4. Reconciliation & idempotency: use idempotent order IDs and reservation state machine (PENDING → RESERVED → CONFIRMED → CANCELLED). Implement background retry, compensating transactions, and automatic release of TTLed reservations.
5. UX & metrics: show clear state, progressive disclosure (pending → confirmed), enable “cancel” while pending. Track oversell rate, time-to-confirm, conversion drop when reservations fail.

Why this balances trade-offs
Delivers mobile-first low-latency UX and offline capability while bounding oversell risk via short server reservations and deterministic reconciliation; keeps complexity server-side with clear client-state handling and transparent user feedback.

Definition — Lamport clocks

• Lamport clocks assign a single integer counter per process. On each local event: counter += 1. On send, include counter; on receive, set counter = max(local, received) + 1.
• They give a partial ordering that respects causality (if A -> B then L(A) < L(B)) but cannot determine concurrency precisely.

Definition — Vector clocks

• Each node keeps a vector of counters (one entry per node). On local event: V[i] += 1. On merge/receive: for all j, V[j] = max(V[j], V_recv[j]) and then increment local entry.
• Comparing vectors: V <= W if every component V[k] <= W[k]. If neither V <= W nor W <= V they are concurrent.

Short example (two devices A and B)

• Start: V_A = [0,0], V_B = [0,0].
• A updates: V_A = [1,0]; sync not yet sent.
• B independently updates: V_B = [0,1].
• When synced, compare [1,0] vs [0,1] — neither <= other ⇒ concurrent updates => conflict detected and need merge/resolution.

Why Lamport can be insufficient in mobile sync

• Lamport might assign L(A)=1 and L(B)=2 (depending on message timing). Since integers are totally ordered, L(A)<L(B) could imply an order that didn’t actually exist; concurrent updates may appear ordered, hiding conflicts. In mobile apps with offline edits on multiple devices, vector clocks are necessary to reliably detect true concurrency so the app can prompt merge, auto-merge, or use CRDTs.

Approach
Use exponential backoff with cap = min(base * 2^attempt, max). Apply "full jitter": return random value uniformly in [0, cap). Inject Random for deterministic tests.

import kotlin.random.Random
import kotlin.math.min
import kotlin.math.pow

// attempt: 0-based attempt number
fun nextBackoff(
    attempt: Int,
    baseMillis: Long = 500,
    maxMillis: Long = 60_000,
    rng: Random = Random
): Long {
    require(attempt >= 0) { "attempt must be non-negative" }
    require(baseMillis > 0 && maxMillis > 0) { "base and max must be > 0" }

    // compute growth safely: cap = min(base * 2^attempt, max)
    // avoid overflow by using Double for pow then clamp to maxMillis
    val exp = if (attempt >= 63) Double.POSITIVE_INFINITY else baseMillis.toDouble() * 2.0.pow(attempt)
    val cap = if (!exp.isFinite()) maxMillis else min(exp.toLong(), maxMillis)

    // full jitter: uniform random in [0, cap)
    if (cap <= 1L) return 0L
    return rng.nextLong(cap)
}

Explanation & notes

• Uses Double pow to prevent Long overflow; attempts >= 63 treated as infinite and capped.
• rng injected for deterministic unit tests (use Random(0) or a mock).
• Time complexity O(1), space O(1).
• Edge cases: attempt large, base > max, cap <=1.
• Example test: nextBackoff(3, 100, 10000, Random(123)) returns reproducible value.

Approach (brief)
Design an SQLite-backed queue (Room) storing Change records with status, idempotency_key, attempt_count, next_retry_at. Use a single-transaction enqueue/dequeue and WorkManager to schedule uploads. Deduplicate on idempotency_key at insert. Exponential backoff computed from attempt_count.

Schema (Room entity)

@Entity(tableName = "changes", indices = [Index(value = ["idempotencyKey"], unique = true)])
data class Change(
  @PrimaryKey val id: String,                 // uuid
  val payload: String,                        // JSON
  val idempotencyKey: String,
  val status: String,                         // PENDING, IN_FLIGHT, COMPLETED, FAILED
  val attemptCount: Int,
  val nextRetryAt: Long,                      // epoch millis
  val createdAt: Long
)

DAO signatures & key queries

@Dao
interface ChangeDao {
  @Insert(onConflict = OnConflictStrategy.IGNORE)
  fun insert(change: Change): Long              // returns -1 if dup

  @Query("SELECT * FROM changes WHERE status = 'PENDING' AND nextRetryAt <= :now ORDER BY createdAt LIMIT :limit")
  fun fetchReady(now: Long, limit: Int): List<Change>

  @Transaction
  fun claimBatch(ids: List<String>) { /* set status='IN_FLIGHT' atomically */ }

  @Query("UPDATE changes SET status = :status WHERE id = :id")
  fun updateStatus(id: String, status: String)

  @Query("DELETE FROM changes WHERE id = :id")
  fun deleteById(id: String)

  @Query("UPDATE changes SET attemptCount = :attempt, nextRetryAt = :next WHERE id = :id")
  fun updateRetry(id: String, attempt: Int, next: Long)
}

Enqueue pseudocode

fun enqueue(changePayload: String, idempotencyKey: String) {
  val id = UUID.randomUUID().toString()
  val now = System.currentTimeMillis()
  val change = Change(id, changePayload, idempotencyKey, "PENDING", 0, now, now)
  val res = dao.insert(change)
  if (res == -1L) { /* duplicate detected — no-op or update payload if desired */ }
  WorkManager.enqueue(OneOffSyncWork) // ensure worker runs
}

Worker (upload loop)

class SyncWorker : CoroutineWorker(...) {
  override suspend fun doWork(): Result {
    val now = System.currentTimeMillis()
    val batch = dao.fetchReady(now, 20)
    if (batch.isEmpty()) return Result.success()

    dao.claimBatch(batch.map { it.id }) // set IN_FLIGHT in transaction

    for (c in batch) {
      try {
        val resp = api.upload(c.payload, c.idempotencyKey) // server dedups by idempotencyKey
        if (resp.success) {
          dao.deleteById(c.id)
        } else {
          scheduleRetry(c)
        }
      } catch (e: Throwable) {
        scheduleRetry(c)
      }
    }
    return Result.success()
  }

  private fun scheduleRetry(c: Change) {
    val nextAttempt = c.attemptCount + 1
    val backoff = min(60_000L * (1 shl (nextAttempt -1)), 24*60*60_1000L) // cap 24h
    val next = System.currentTimeMillis() + backoff
    dao.updateRetry(c.id, nextAttempt, next)
    dao.updateStatus(c.id, "PENDING")
  }
}

Resumability & Idempotency

• Persisted state survives restarts in Room DB.
• IdempotencyKey unique index prevents duplicate enqueue.
• Server should support idempotency keys; client includes key with upload.
• WorkManager ensures retry across app restarts; nextRetryAt prevents premature work.

Transactions & concurrency

• claimBatch runs inside a DB transaction: select FOR UPDATE semantics via Room @Transaction to set status IN_FLIGHT only for fetched ids to avoid double-processing across workers.

Edge cases & notes

• Handle long-running IN_FLIGHT on crash: a periodic job resets IN_FLIGHT older than threshold to PENDING.
• Consider tombstones for COMPLETED items retention policy.
• Encrypt payloads if sensitive.