FSD Frontend System Design

Part VI — The Blueprint · Lesson 11.8

HLD – Email Client

In one lineAn offline-first local database that syncs both ways — the design is the sync protocol.

Where you've seen itTriaging your inbox offline, then watching every action apply correctly once you reconnect.

  • Time20 min
  • DiagramIndexedDB schema + two-way sync with a watermark
  • Chapter11 · High Level Design

Diagram

diagram
1–2 · SCOPE AND SCALE

  in scope   list · read · compose/send · search · labels · offline
  out        calendar · contacts · spam ML · attachments storage
  scale      50k messages per mailbox · offline is a core requirement
             multi-device: same account open in three places
diagram
3–4 · LOCAL-FIRST ARCHITECTURE

  ┌──────────────────────────────────────────────┐
  │  UI reads ONLY from IndexedDB (6.5)          │  ← instant, always
  ├──────────────────────────────────────────────┤
  │  messages   keyPath id · index by-thread,    │
  │                          by-date, by-label   │
  │  threads    id, messageIds[], lastMessageAt  │
  │  outbox     queued sends + pending actions   │
  │  meta       syncWatermark, deviceId          │
  └───────────────────┬──────────────────────────┘
                      │  sync engine (service worker, 9.1)
                      ▼
              ┌──────────────┐
              │  Mail API    │
              └──────────────┘

  The UI never waits on the network. Ever.
diagram
6a · DEEP DIVE — TWO-WAY SYNC

  PULL                                PUSH
  GET /changes?since=<watermark>      replay outbox in order
       │                                   │
       ▼                                   ▼
  [{id, op:'update', labels:[...]},   POST /messages/9/archive
   {id, op:'delete'}, ...]                 │
       │                              ┌────┴─────┐
       ▼                            ack        conflict
  apply to IndexedDB                  │            │
  watermark = response.cursor    remove from   resolve (below)
                                   outbox

  Watermark = server-issued cursor, NOT a client clock —
  device clocks are wrong and unsynchronised.
diagram
6b · DEEP DIVE — CONFLICT RESOLUTION

  conflict type                     resolution
  ────────────────────────────────────────────────────────────
  label add/remove (commutative)    merge — apply both sides
  read/unread flag                  last-write-wins by server time
  delete vs edit                    delete wins, warn the user
  draft edited on two devices       keep both, surface "2 versions"
                                    ← never silently discard user text

  Rule: commutative ops merge; destructive ops need an explicit rule;
        user-authored content is never auto-discarded.

How it works

  1. Read path is local only — the UI queries IndexedDB, so the inbox opens instantly and works offline.
  2. Write path is optimistic: apply locally, enqueue in the outbox, replay on reconnect (9.1).
  3. Sync pulls a delta since the server watermark; full re-sync only on first login or corruption.
  4. Search runs locally over an IndexedDB index for cached mail, falling back to server search for older messages.
  5. Virtualize the message list (10.7) — 50,000 rows will not live in the DOM.

Trade-offs

ChoiceCost
Local-first readsStorage quota, eviction handling, migrations
Optimistic writesConflict resolution UI you must design
Local search indexBuild cost and staleness
Full sync on loginSlow first run; simple correctness

Interview angle

"The user archives 20 emails offline. What happens?"

  • Each action applies to IndexedDB immediately and appends to an ordered outbox; the UI reflects it at once.
  • On reconnect the outbox replays in order with idempotency keys, so retries can't double-apply.
  • Conflicts resolve by type — label changes merge, deletes win over edits, and conflicting drafts are kept as two versions rather than silently dropped.

Recap

  • The UI reads only from the local database; the network is a background concern.
  • Sync is a server-issued watermark plus an ordered outbox, never a client clock.
  • Classify conflicts: merge commutative ops, define rules for destructive ones, never discard user text.