Email Client (e.g. Microsoft Outlook)

Typical power user:
  Accounts: 2–3 (personal Gmail + work Outlook + newsletter catch-all)
  Total messages: ~200K across all accounts (10 years of email)
  Inbox messages: ~5K unread/recent
  Messages received/day: ~100 (50 real + 50 automated/newsletters)
  Messages sent/day: ~30

Storage estimation:
  Average message header + body (text): ~5KB
  200K messages × 5KB = ~1GB raw text
  SQLite with FTS5 index overhead: ~1.5GB total
  Attachment cache (most recent 6 months): ~3GB

Memory budget (Electron app):
  Active message list (500 rows metadata): ~500KB
  Open thread (10 messages with HTML): ~2MB
  Contact autocomplete index: ~5MB (50K contacts)
  Total working memory: < 200MB

Sync bandwidth:
  New mail check (IMAP IDLE): ~0 bandwidth (push notification)
  Full sync (initial setup, 200K messages headers): ~1GB one-time
  Incremental sync: ~50KB/day (100 new message headers + bodies)

Operations per session:
  Read messages: ~50
  Archive/delete: ~30
  Compose/send: ~5
  Search: ~10

<App>
  <ThemeProvider>
    <KeyboardShortcutProvider>
      <SplitPaneLayout>
        <FolderSidebar>              ← 200px, resizable
          <AccountGroup>             ← collapsible per account
            <FolderItem />           ← with unread badge
          </AccountGroup>
          <UnifiedInboxToggle />
        </FolderSidebar>

        <MessageListPane>            ← 300–400px, resizable
          <SearchBar />              ← with filter chips
          <BulkActionBar />          ← visible when multi-selecting
          <VirtualizedMessageList>
            <MessageRow />           ← star, checkbox, subject, sender, date, snippet
          </VirtualizedMessageList>
        </MessageListPane>

        <DetailPane>                 ← fills remaining space
          <ThreadView>               ← collapsed messages in thread
            <MessageDetail>          ← sandboxed HTML rendering
              <MessageHeader />      ← from, to, cc, date, attachments
              <SandboxedHtmlFrame /> ← iframe with CSP
              <AttachmentList />
            </MessageDetail>
          </ThreadView>
          — OR —
          <ComposeView>              ← rich text editor
            <RecipientField />       ← token input with autocomplete
            <SubjectField />
            <RichTextEditor />       ← TipTap / ProseMirror
            <AttachmentUploader />
            <SendButton />
          </ComposeView>
        </DetailPane>
      </SplitPaneLayout>
    </KeyboardShortcutProvider>
  </ThemeProvider>
</App>

CREATE TABLE accounts (
  id TEXT PRIMARY KEY,
  email TEXT NOT NULL,
  display_name TEXT NOT NULL,
  provider TEXT NOT NULL,  -- 'gmail' | 'outlook' | 'icloud' | 'imap-generic'
  imap_host TEXT NOT NULL,
  imap_port INTEGER NOT NULL,
  smtp_host TEXT NOT NULL,
  smtp_port INTEGER NOT NULL,
  last_synced_at INTEGER
);

CREATE TABLE folders (
  id TEXT PRIMARY KEY,
  account_id TEXT NOT NULL REFERENCES accounts(id),
  name TEXT NOT NULL,
  role TEXT NOT NULL,  -- 'inbox' | 'sent' | 'drafts' | 'trash' | 'archive' | 'spam' | 'custom'
  unread_count INTEGER DEFAULT 0,
  total_count INTEGER DEFAULT 0,
  parent_folder_id TEXT REFERENCES folders(id),
  imap_uidvalidity INTEGER,
  imap_highest_modseq INTEGER
);

CREATE TABLE threads (
  id TEXT PRIMARY KEY,
  account_id TEXT NOT NULL REFERENCES accounts(id),
  subject TEXT NOT NULL,
  snippet TEXT NOT NULL,
  last_message_at INTEGER NOT NULL,
  is_unread INTEGER DEFAULT 0,
  is_starred INTEGER DEFAULT 0,
  has_attachments INTEGER DEFAULT 0,
  message_count INTEGER DEFAULT 1
);

CREATE TABLE messages (
  id TEXT PRIMARY KEY,
  thread_id TEXT NOT NULL REFERENCES threads(id),
  account_id TEXT NOT NULL REFERENCES accounts(id),
  folder_id TEXT NOT NULL REFERENCES folders(id),
  message_id_header TEXT,  -- RFC 2822 Message-ID
  in_reply_to TEXT,
  from_name TEXT NOT NULL,
  from_email TEXT NOT NULL,
  to_json TEXT NOT NULL,   -- JSON array of {name, email}
  cc_json TEXT,
  bcc_json TEXT,
  subject TEXT NOT NULL,
  body_text TEXT,
  body_html TEXT,
  received_at INTEGER NOT NULL,
  is_read INTEGER DEFAULT 0,
  is_starred INTEGER DEFAULT 0,
  is_draft INTEGER DEFAULT 0,
  imap_uid INTEGER,
  flags_json TEXT           -- JSON array of IMAP flags
);

CREATE INDEX idx_messages_folder ON messages(folder_id, received_at DESC);
CREATE INDEX idx_messages_thread ON messages(thread_id, received_at ASC);
CREATE INDEX idx_messages_unread ON messages(folder_id, is_read) WHERE is_read = 0;

-- Full-text search index
CREATE VIRTUAL TABLE messages_fts USING fts5(
  subject, from_name, from_email, body_text,
  content=messages, content_rowid=rowid
);

CREATE TABLE attachments (
  id TEXT PRIMARY KEY,
  message_id TEXT NOT NULL REFERENCES messages(id),
  filename TEXT NOT NULL,
  mime_type TEXT NOT NULL,
  size_bytes INTEGER NOT NULL,
  content_id TEXT,         -- for inline images (cid: references)
  is_downloaded INTEGER DEFAULT 0,
  local_path TEXT
);

CREATE TABLE outbox (
  id TEXT PRIMARY KEY,
  account_id TEXT NOT NULL REFERENCES accounts(id),
  draft_json TEXT NOT NULL,  -- serialized Draft object
  status TEXT DEFAULT 'pending',  -- 'pending' | 'sending' | 'failed'
  attempts INTEGER DEFAULT 0,
  last_attempt_at INTEGER,
  error_message TEXT,
  created_at INTEGER NOT NULL
);

CREATE TABLE contacts (
  id TEXT PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  name TEXT,
  frequency INTEGER DEFAULT 1,  -- communication frequency for ranking
  last_contacted_at INTEGER
);

type Account = {
  id: string;
  email: string;
  displayName: string;
  provider: "gmail" | "outlook" | "icloud" | "imap-generic";
  lastSyncedAt: number | null;
  syncStatus: "idle" | "syncing" | "error";
};

type Folder = {
  id: string;
  accountId: string;
  name: string;
  role: "inbox" | "sent" | "drafts" | "trash" | "archive" | "spam" | "custom";
  unreadCount: number;
  totalCount: number;
  parentFolderId: string | null;
  children: Folder[]; // for tree rendering
};

type ThreadSummary = {
  id: string;
  accountId: string;
  subject: string;
  snippet: string;
  participants: Array<{ name: string; email: string }>;
  lastMessageAt: number;
  isUnread: boolean;
  isStarred: boolean;
  hasAttachments: boolean;
  messageCount: number;
};

type Message = {
  id: string;
  threadId: string;
  from: { name: string; email: string };
  to: Array<{ name: string; email: string }>;
  cc: Array<{ name: string; email: string }>;
  subject: string;
  bodyText: string;
  bodyHtml: string;
  receivedAt: number;
  isRead: boolean;
  isStarred: boolean;
  attachments: Attachment[];
};

type Attachment = {
  id: string;
  filename: string;
  mimeType: string;
  sizeBytes: number;
  contentId: string | null;
  isDownloaded: boolean;
  localPath: string | null;
  downloadProgress: number; // 0–100, for active downloads
};

type Draft = {
  id: string;
  accountId: string;
  threadId: string | null;
  inReplyToMessageId: string | null;
  replyType: "reply" | "reply-all" | "forward" | null;
  to: Array<{ name: string; email: string }>;
  cc: Array<{ name: string; email: string }>;
  bcc: Array<{ name: string; email: string }>;
  subject: string;
  bodyHtml: string;
  attachments: Attachment[];
  lastSavedAt: number;
};

interface MailDataAccess {
  // Folder operations
  getFolders(accountId: string): Folder[];
  getUnifiedInbox(): ThreadSummary[];

  // Thread/message queries (paginated, from SQLite)
  getThreads(query: ThreadQuery): {
    threads: ThreadSummary[];
    totalCount: number;
  };
  getMessages(threadId: string): Message[];
  getMessage(messageId: string): Message;

  // Mutations (applied locally + queued for sync)
  markAsRead(messageIds: string[]): void;
  markAsUnread(messageIds: string[]): void;
  star(threadIds: string[]): void;
  unstar(threadIds: string[]): void;
  moveToFolder(threadIds: string[], targetFolderId: string): void;
  deleteThreads(threadIds: string[]): void;
  archiveThreads(threadIds: string[]): void;

  // Search
  search(query: SearchQuery): { threads: ThreadSummary[]; totalCount: number };

  // Compose
  saveDraft(draft: Draft): Draft;
  sendMessage(draft: Draft): void; // moves to outbox
  discardDraft(draftId: string): void;

  // Contacts
  searchContacts(query: string, limit: number): Contact[];
}

type ThreadQuery = {
  folderId: string;
  page: number;
  pageSize: number; // default 50
  sortBy: "date" | "subject" | "sender";
  sortDir: "asc" | "desc";
  filterUnread?: boolean;
  filterStarred?: boolean;
};

type SearchQuery = {
  text?: string;
  from?: string;
  to?: string;
  subject?: string;
  hasAttachment?: boolean;
  isUnread?: boolean;
  isStarred?: boolean;
  folderId?: string;
  accountId?: string;
  dateAfter?: number;
  dateBefore?: number;
  page: number;
  pageSize: number;
};

interface SyncEngine {
  // Account management
  addAccount(config: AccountConfig): Promise<void>;
  removeAccount(accountId: string): Promise<void>;

  // Sync control
  syncAll(): void; // trigger sync for all accounts
  syncFolder(folderId: string): void; // sync specific folder
  pauseSync(): void;
  resumeSync(): void;

  // Status
  getSyncStatus(accountId: string): SyncStatus;
  onSyncProgress(callback: (progress: SyncProgress) => void): () => void;
  onNewMail(callback: (accountId: string, count: number) => void): () => void;

  // Outbox
  getOutboxEntries(): OutboxEntry[];
  retryOutboxEntry(entryId: string): void;
  cancelOutboxEntry(entryId: string): void;
}

type SyncStatus = {
  state: "idle" | "syncing" | "error";
  lastSyncedAt: number | null;
  error: string | null;
  progress: { current: number; total: number } | null;
};

type OutboxEntry = {
  id: string;
  accountId: string;
  subject: string;
  to: string[];
  status: "pending" | "sending" | "failed";
  attempts: number;
  lastAttemptAt: number | null;
  error: string | null;
  createdAt: number;
};

// Delta sync using IMAP CONDSTORE extension
async function syncFolder(account: Account, folder: Folder): Promise<void> {
  const connection = await imapConnect(account);

  // 1. Check for new messages since last known UID
  const newMessages = await connection.fetch(`${folder.lastUid + 1}:*`, {
    envelope: true,
    bodystructure: true,
    flags: true,
  });

  // 2. Check for flag changes since last HIGHESTMODSEQ
  const changedFlags = await connection.fetch("1:*", {
    flags: true,
    modseq: folder.highestModseq,
  });

  // 3. Check for expunged messages
  const expunged = await connection.expungedSince(folder.highestModseq);

  // 4. Apply changes to local SQLite
  await db.transaction(() => {
    for (const msg of newMessages) insertMessage(msg);
    for (const change of changedFlags) updateFlags(change);
    for (const uid of expunged) deleteMessage(uid);
    updateFolderSyncState(folder.id, connection.highestModseq);
  });

  // 5. Enter IDLE for real-time push
  connection.idle();
  connection.on("mail", () => syncFolder(account, folder));
}

T=0ms     Electron main process starts
T=50ms    Browser window created, shell HTML loads
T=100ms   React app mounts, reads folder tree from SQLite (< 50ms for 200 folders)
T=150ms   Sidebar renders with folder names + cached unread counts
T=200ms   Message list queries SQLite for Inbox threads (page 1, 50 items)
T=250ms   Message list renders (virtualized, only 15 visible rows)
T=300ms   App is interactive — user can click folders, scroll, search

Background (non-blocking):
T=500ms   Sync engine starts, connects to all accounts via IMAP
T=2000ms  First sync completes, unread counts may update
T=5000ms  IMAP IDLE connections established (real-time push)

┌─────────────────────────────────────────────────────────┐
│  Parent React App (main frame)                          │
│                                                          │
│  ┌─────────────────────────────────────────────────┐   │
│  │  <iframe                                         │   │
│  │    sandbox="allow-same-origin"                    │   │
│  │    csp="script-src 'none'; object-src 'none'"    │   │
│  │    srcdoc={sanitizedHtml}                         │   │
│  │  />                                               │   │
│  │                                                   │   │
│  │  Email HTML renders here (isolated from app)      │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

CREATE VIRTUAL TABLE messages_fts USING fts5(
  subject,
  from_name,
  from_email,
  body_text,
  content=messages,
  content_rowid=rowid,
  tokenize='porter unicode61'
);

-- Full-text search
SELECT m.* FROM messages m
JOIN messages_fts ON messages_fts.rowid = m.rowid
WHERE messages_fts MATCH 'invoice AND from_email:accounting*'
ORDER BY rank
LIMIT 50 OFFSET 0;

-- Structured filter
SELECT * FROM messages
WHERE folder_id = ? AND is_read = 0 AND received_at > ?
ORDER BY received_at DESC
LIMIT 50;

// main.js — BrowserWindow configuration
const mainWindow = new BrowserWindow({
  webPreferences: {
    contextIsolation: true, // renderer cannot access Node.js
    nodeIntegration: false, // no require() in renderer
    sandbox: true, // Chromium sandbox enabled
    webSecurity: true, // enforce same-origin policy
    allowRunningInsecureContent: false,
    enableRemoteModule: false, // deprecated, ensure disabled
  },
});

// Preload script exposes ONLY the mail API via contextBridge
contextBridge.exposeInMainWorld("mailAPI", {
  getFolders: (accountId) => ipcRenderer.invoke("mail:getFolders", accountId),
  getThreads: (query) => ipcRenderer.invoke("mail:getThreads", query),
  // ... only whitelisted operations
});

function processEmailHtml(html: string, senderEmail: string): string {
  const doc = new DOMParser().parseFromString(html, "text/html");

  const images = doc.querySelectorAll("img");
  for (const img of images) {
    const src = img.getAttribute("src");

    if (src?.startsWith("cid:")) {
      // Inline image — resolve to local attachment path
      img.setAttribute("src", resolveContentId(src));
    } else if (isRemoteUrl(src)) {
      if (isSenderTrusted(senderEmail)) {
        // Trusted sender — proxy through our image cache
        img.setAttribute("src", proxyUrl(src));
      } else {
        // Untrusted — replace with placeholder
        img.setAttribute("src", "data:image/svg+xml,..."); // placeholder icon
        img.setAttribute("data-original-src", src);
        img.classList.add("blocked-image");
      }
    }
  }

  return doc.documentElement.outerHTML;
}

<div role="application" aria-label="Email Client">
  <nav role="navigation" aria-label="Folders">
    <div role="tree" aria-label="Account folders">
      <div role="treeitem" aria-expanded="true" aria-selected="{isActive}">
        Inbox (3 unread)
      </div>
    </div>
  </nav>

  <main role="main" aria-label="Messages">
    <div role="listbox" aria-label="Message list" aria-multiselectable="true">
      <div
        role="option"
        aria-selected="{isSelected}"
        aria-label="From Alice: Meeting tomorrow, received 2 hours ago, unread"
      >
        ...
      </div>
    </div>
  </main>

  <section role="region" aria-label="Message detail" aria-live="polite">
    ...
  </section>
</div>