09. Offline-First POS & SWR Confirmed Mutation LedgerCopy Anchor Link

Production Paradigm: UUIDv7 Timestamp Ordering + IndexedDB Persistent Outbox + Stale-While-Revalidate (SWR) Service Worker + Confirmed Mutation Ledger with 304 Overwrite Guard.

💥 The Real-World BottleneckCopy Anchor Link

Retail Point of Sale (POS), field service apps, and event ticket check-ins frequently operate under unstable network conditions (underground venues, spotty 3G/4G, Wi-Fi drops).

Naive web applications suffer catastrophic failures:

1. White Screen & Crashes: When connectivity drops, the POS application fails to record customer sales, freezing store checkout lines.
2. The Stale-304 Overwrite Disaster: When a device reconnects, an outdated HTTP 304 cache response or background revalidation can overwrite optimistic local edits made while offline.
3. Data Overwrite & Conflict Loss: Two staff members modifying the same order or inventory line offline result in lost records when synchronizing simultaneously to the central database.

🏛️ High-Concurrency ArchitectureCopy Anchor Link

This blueprint implements an offline-first local-first architecture: every user action is recorded into a local persistent ledger using monotonically ordered UUIDv7 tokens before background synchronization.

Key Architectural PhasesCopy Anchor Link

1. UUIDv7 Time-Ordered Monotonic Identifiers (uuidv7):
   • Generates 128-bit identifiers with millisecond-precision timestamps embedded in the leading bits.
   • Orders offline transactions deterministically without centralized clock synchronization.
2. Optimistic Local Ledger (OfflinePOSStore):
   • Commits mutations to IndexedDB in < 2ms, allowing the cashier to print receipts immediately without waiting for server network roundtrips.
3. Confirmed Mutation Ledger (ConfirmedMutationLedger):
   • Maintains an in-memory and cached ledger of confirmed mutations with entity timestamps.
   • Prevents stale SWR cache responses or HTTP 304 Not Modified headers from overwriting newer local edits.
4. Deterministic Conflict Resolver (ConflictResolver):
   • Applies field-level merge strategies (Last-Write-Wins based on UUIDv7 timestamps, additive inventory increments) when multiple devices synchronize concurrent edits.

🧩 Composed Functional SlicesCopy Anchor Link

💻 Code ImplementationCopy Anchor Link

mkdir -p src/lib/offline
cp packages/async-sync/src/uuidv7.ts src/lib/offline/
cp packages/async-sync/src/sync-engine.ts src/lib/offline/
cp packages/async-sync/src/outbox-queue.ts src/lib/offline/
cp packages/spa-version-guard/src/pwa-swr/confirmed-ledger.ts src/lib/offline/

import { uuidv7 } from '@/lib/offline/uuidv7';
import { SyncEngine, ConflictResolver } from '@/lib/offline/sync-engine';
import { ConfirmedMutationLedger } from '@/lib/offline/confirmed-ledger';

const confirmedLedger = new ConfirmedMutationLedger();

export async function createPosOrder(cart: { skuId: string; qty: number; price: number }[]) {
  // 1. Generate monotonic timestamped ID
  const orderId = uuidv7();

  const orderRecord = {
    id: orderId,
    items: cart,
    total: cart.reduce((sum, item) => sum + item.qty * item.price, 0),
    createdAt: new Date().toISOString(),
    synced: false,
  };

  // 2. Commit to local ledger (0ms wait)
  await localDb.orders.put(orderRecord);
  confirmedLedger.registerLocalMutation('order', orderId, Date.now());

  // 3. Queue in background sync outbox
  syncQueue.enqueue({
    type: 'ORDER_CREATED',
    id: orderId,
    payload: orderRecord,
  });

  return orderRecord;
}

📊 Production Scale Benchmark & VerificationCopy Anchor Link