Offline states and correctness

Measurable targets

Email client frontend system design scope

Mailbox route and responsive panes
  -> normalized selectors
  -> mailbox facade
       -> snapshot and delta coordinator
       -> durable draft repository
       -> idempotent outbox coordinator
       -> safe body and attachment cache
  -> account-scoped IndexedDB
  -> versioned mailbox service

Push, SSE, or BroadcastChannel
  -> invalidation hint only
  -> fetch authoritative delta
  -> reconcile through one reducer

Offline email client architecture invariants

Expired cursor recovery

Worked example: the send succeeds and the response disappears

offline: persist d-19 + cmd-73 -> show Queued
reconnect: POST send(cmd-73) -> server creates m-205
network: response disappears
sync: message.upserted(m-205, clientCommandId = cmd-73)
reconcile: add m-205 once -> acknowledge cmd-73 -> retire d-19

Email client state management entities

type MailboxAddress = {
  name?: string;
  address: string;
};

type Thread = {
  id: string;
  messageIds: readonly string[];
  labelIds: readonly string[];
  subject: string;
  snippet: string;
  participants: readonly MailboxAddress[];
  lastMessageAt: string;
  unreadMessageCount: number;
  revision: string;
};

type Message = {
  readonly id: string;
  readonly threadId: string;
  readonly labelIds: readonly string[];
  readonly from: MailboxAddress;
  readonly to: readonly MailboxAddress[];
  readonly sentAt: string;
  readonly subject: string;
  readonly snippet: string;
  readonly bodyResourceId: string;
  readonly attachmentIds: readonly string[];
  readonly revision: string;
  readonly clientCommandId?: string;
};

type Label = {
  id: string;
  name: string;
  kind: 'system' | 'user';
  color?: string;
  revision: string;
};

type MailboxSnapshot = {
  mailboxId: string;
  syncCursor: string;
  threads: readonly Thread[];
  messages: readonly Message[];
  labels: readonly Label[];
  capturedAt: string;
};

type DraftAttachmentBase = {
  attachmentId: string;
  draftId: string;
  fileName: string;
  contentType: string;
  sizeBytes: number;
};

type DraftAttachment =
  | (DraftAttachmentBase & {
      status: 'selected';
      uploadedBytes: 0;
    })
  | (DraftAttachmentBase & {
      status: 'uploading' | 'processing';
      uploadSessionId: string;
      uploadedBytes: number;
    })
  | (DraftAttachmentBase & {
      status: 'ready';
      uploadSessionId: string;
      uploadedBytes: number;
      assetId: string;
      assetRevision: string;
    })
  | (DraftAttachmentBase & {
      status: 'failed';
      uploadSessionId?: string;
      uploadedBytes: number;
      failureCode: string;
      retryable: boolean;
    })
  | (DraftAttachmentBase & {
      status: 'blocked';
      uploadSessionId: string;
      uploadedBytes: number;
      assetId: string;
      failureCode: string;
    })
  | (DraftAttachmentBase & {
      status: 'canceled';
      uploadedBytes: number;
    });

type DraftContent = {
  to: readonly MailboxAddress[];
  cc: readonly MailboxAddress[];
  bcc: readonly MailboxAddress[];
  subject: string;
  bodyHtml: string;
  attachmentIds: readonly string[];
};

type DraftDocument = {
  draftId: string;
  mailboxId: string;
  threadId?: string;
  content: DraftContent;
  contentRevision: number;
  baseRemoteRevision: string | null;
  remoteRevision?: string;
  updatedAt: string;
};

type RemoteDraftRevision = {
  draftId: string;
  mailboxId: string;
  threadId?: string;
  content: DraftContent;
  revision: string;
  acknowledgedContentRevision?: number;
  updatedAt: string;
};

Frontend email outbox pattern and durable intent

type CommandBase = {
  commandId: string;
  idempotencyKey: string;
  baseRevision: string | null;
  createdAt: string;
};

type OutboxCommand =
  | (CommandBase & {
      kind: 'draft.save';
      draftId: string;
      document: DraftDocument;
    })
  | (CommandBase & {
      kind: 'draft.send';
      draftId: string;
      expectedContentRevision: number;
      attachmentAssetIds: readonly string[];
    })
  | (CommandBase & {
      kind: 'thread.labels.set';
      threadId: string;
      addLabelIds: readonly string[];
      removeLabelIds: readonly string[];
    });

type PendingCommand = {
  command: OutboxCommand;
  status: 'queued' | 'submitting' | 'awaiting-delta' | 'conflict' | 'failed';
  attemptCount: number;
  retryAfter?: string;
  lastErrorCode?: string;
};

type MailboxProjection = {
  threadsById: Record<string, Thread>;
  messagesById: Record<string, Message>;
  labelsById: Record<string, Label>;
  remoteDraftsById: Record<string, RemoteDraftRevision>;
  syncCursor: string | null;
  phase: 'empty' | 'cached' | 'syncing' | 'fresh' | 'stale' | 'recovering';
};

type LocalIntentState = {
  draftsById: Record<string, DraftDocument>;
  attachmentsById: Record<string, DraftAttachment>;
  commandsById: Record<string, PendingCommand>;
};

type MailboxClientState = {
  projection: MailboxProjection;
  localIntent: LocalIntentState;
  view: {
    selectedThreadId?: string;
    activeLabelId?: string;
    query: string;
  };
  resources: {
    bodyCacheKeys: readonly string[];
    attachmentCacheKeys: readonly string[];
    localSearchVersion?: string;
  };
};

Revision and deletion semantics

Snapshot, delta, and detail reads

type CommandOutcome =
  | {
      commandId: string;
      status: 'applied';
      clientCommandId: string;
      serverRevision: string;
    }
  | {
      commandId: string;
      status: 'conflict';
      currentRevision: string;
      reason: 'revision-mismatch' | 'draft-replaced' | 'already-sent';
    }
  | {
      commandId: string;
      status: 'rejected';
      reason: 'invalid' | 'forbidden' | 'attachment-unavailable';
    };

type MailboxEvent =
  | { type: 'message.upserted'; eventId: string; message: Message; clientCommandId?: string }
  | { type: 'message.removed'; eventId: string; messageId: string; revision: string }
  | { type: 'thread.updated'; eventId: string; thread: Thread }
  | { type: 'label.updated'; eventId: string; label: Label }
  | { type: 'draft.replaced'; eventId: string; draft: RemoteDraftRevision; clientCommandId?: string };

type MailboxDelta = {
  mailboxId: string;
  afterCursor: string;
  syncCursor: string;
  events: readonly MailboxEvent[];
  commandOutcomes: readonly CommandOutcome[];
  hasMore: boolean;
};

type ThreadDetail = {
  thread: Thread;
  messages: readonly Message[];
};

type MessageBodyResource = {
  messageId: string;
  sourceRevision: string;
  contentType: 'text/plain' | 'text/html';
  content: string;
  hasRemoteImages: boolean;
  attachmentIds: readonly string[];
};

Gateway and reducer boundaries

type SaveDraftResult = {
  draft: RemoteDraftRevision;
  clientCommandId: string;
};

type SendAccepted = {
  status: 'accepted';
  commandId: string;
  clientCommandId: string;
  reconciliation: 'await-mailbox-delta';
};

type LabelCommandResult = {
  status: 'applied' | 'accepted';
  commandId: string;
  clientCommandId: string;
  threadRevision?: string;
};

type AttachmentUploadSession = {
  uploadSessionId: string;
  attachmentId: string;
  committedBytes: number;
  expiresAt: string;
};

type AttachmentAsset = {
  assetId: string;
  assetRevision: string;
  readiness: 'processing' | 'ready' | 'blocked';
};

type AttachmentDownload = {
  assetId: string;
  url: string;
  expiresAt: string;
  contentDisposition: 'inline' | 'attachment';
};

interface MailboxGateway {
  getSnapshot(input: {
    mailboxId: string;
    labelId?: string;
    pageToken?: string;
    signal: AbortSignal;
  }): Promise<{ snapshot: MailboxSnapshot; nextPageToken?: string }>;
  getChanges(input: {
    mailboxId: string;
    after: string;
    signal: AbortSignal;
  }): Promise<MailboxDelta>;
  getThread(threadId: string, signal: AbortSignal): Promise<ThreadDetail>;
  getMessageBody(messageId: string, signal: AbortSignal): Promise<MessageBodyResource>;
  createAttachmentUpload(input: {
    draftId: string;
    attachmentId: string;
    fileName: string;
    contentType: string;
    sizeBytes: number;
    idempotencyKey: string;
    signal: AbortSignal;
  }): Promise<AttachmentUploadSession>;
  uploadAttachmentBytes(input: {
    uploadSessionId: string;
    offset: number;
    bytes: Blob;
    signal: AbortSignal;
    onProgress: (uploadedBytes: number) => void;
  }): Promise<{ committedBytes: number }>;
  finalizeAttachmentUpload(input: {
    uploadSessionId: string;
    idempotencyKey: string;
    signal: AbortSignal;
  }): Promise<AttachmentAsset>;
  getAttachmentAsset(assetId: string, signal: AbortSignal): Promise<AttachmentAsset>;
  cancelAttachmentUpload(input: {
    uploadSessionId: string;
    idempotencyKey: string;
    signal: AbortSignal;
  }): Promise<void>;
  createAttachmentDownload(assetId: string, signal: AbortSignal): Promise<AttachmentDownload>;
  saveDraft(command: Extract<OutboxCommand, { kind: 'draft.save' }>): Promise<SaveDraftResult>;
  sendDraft(command: Extract<OutboxCommand, { kind: 'draft.send' }>): Promise<SendAccepted>;
  setThreadLabels(
    command: Extract<OutboxCommand, { kind: 'thread.labels.set' }>,
  ): Promise<LabelCommandResult>;
}

type DraftReconciliation =
  | { status: 'acknowledged'; draftId: string; baseRemoteRevision: string }
  | { status: 'base-advanced'; draftId: string; baseRemoteRevision: string; preservedContentRevision: number }
  | { status: 'conflict'; draftId: string; remote: RemoteDraftRevision; localContentRevision: number };

declare function upsertMessage(projection: MailboxProjection, message: Message): void;
declare function removeMessage(projection: MailboxProjection, messageId: string, revision: string): void;
declare function upsertThread(projection: MailboxProjection, thread: Thread): void;
declare function upsertLabel(projection: MailboxProjection, label: Label): void;
declare function reconcileRemoteDraft(
  projection: MailboxProjection,
  localIntent: LocalIntentState,
  draft: RemoteDraftRevision,
  clientCommandId?: string,
): DraftReconciliation;

function assertNever(value: never): never {
  throw new Error(`Unsupported mailbox event: ${String(value)}`);
}

function applyMailboxEvent(
  projection: MailboxProjection,
  localIntent: LocalIntentState,
  event: MailboxEvent,
): void {
  switch (event.type) {
    case 'message.upserted':
      upsertMessage(projection, event.message);
      return;
    case 'message.removed':
      removeMessage(projection, event.messageId, event.revision);
      return;
    case 'thread.updated':
      upsertThread(projection, event.thread);
      return;
    case 'label.updated':
      upsertLabel(projection, event.label);
      return;
    case 'draft.replaced':
      reconcileRemoteDraft(projection, localIntent, event.draft, event.clientCommandId);
      return;
    default:
      assertNever(event);
  }
}

Versioned command endpoints

PUT /drafts/draft_91
If-Match: draft-r12
Idempotency-Key: idem-save-91-13
Content-Type: application/json

{
  "commandId": "cmd-save-13",
  "clientCommandId": "cmd-save-13",
  "baseRevision": "draft-r12",
  "contentRevision": 13,
  "content": {
    "to": [{ "address": "reader@example.com" }],
    "cc": [],
    "bcc": [],
    "subject": "Offline notes",
    "bodyHtml": "<p>Draft body</p>",
    "attachmentIds": []
  }
}

POST /drafts/draft_91/send
If-Match: draft-r13
Idempotency-Key: idem-send-91
Content-Type: application/json

{
  "commandId": "cmd-send-91",
  "clientCommandId": "cmd-send-91",
  "baseRevision": "draft-r13",
  "expectedContentRevision": 13,
  "attachmentAssetIds": []
}

202 Accepted
{
  "status": "accepted",
  "commandId": "cmd-send-91",
  "clientCommandId": "cmd-send-91",
  "reconciliation": "await-mailbox-delta"
}

Search has two explicit scopes

Virtualized inbox and bounded resources

IndexedDB quota and multi-tab coordination

HTML security, remote content, and accessibility

Recovery behavior by fault

Measurement, testing, and rollout