margin-mail/docs/architecture.md

# Architecture

Tauri 2, React 19, Vite, TypeScript and zustand on the front, Rust behind. The same stack as
margin and Margin Calendar, so OAuth, token sealing, the build and bundle setup, the overlay
title bar and the phone chrome carry over rather than being invented again. The conventions are
the calendar's, in `../margin-caledar/docs/conventions.md`, and apply here unchanged.

The split is strict. Rust owns authentication, every byte to and from a mail provider, the local
mirror, the sync loop, MIME parsing, HTML sanitising, the portable state database, the journal
and the backup store. TypeScript owns rendering and interaction. The frontend never talks to a
provider, which keeps the content security policy locked to `ipc:` as in the siblings.

The facts about the Gmail API that this design rests on are in
[research/gmail-api.md](research/gmail-api.md), checked against Google's pages on 3 September
2026.

## Two databases, one boundary

There are two SQLite databases per account and the boundary between them is the product.

The **mirror** is a copy of the mailbox: messages, threads, labels, bodies, attachment metadata,
an FTS5 index, the provider's sync cursor, and an outbox. It is derived from the provider and can
be thrown away and rebuilt. Its keys are the provider's ids.

The **state** database is everything the user decided: sender rules, pile membership, snoozes,
notes, renames, merges, clips, ignore flags, notification opt-ins, contact notes. It is never
derived, it is never sent to the provider, and its keys are portable: a thread is identified by
the RFC `Message-ID` of its earliest message (the thread key), a message by its own `Message-ID`,
a sender by their address or domain. Provider ids appear in the state database nowhere. When the
user moves to another provider and the same mail arrives through IMAP with the same
`Message-ID`s, every decision reattaches.

A view is the mirror joined to the state. The Inbox is "threads whose sender rule says Inbox, or
that carry a reply to a thread we are in, minus piles, minus snoozes, minus archived", grouped by
seen state. The join is computed in Rust and served to the frontend as a flat, ordered list of
thread summaries; the frontend never sees a label id or a rule.

## The provider trait

```
trait Provider {
    fn authenticate(...)                 // interactive, returns a sealed credential
    fn full_list(...)                    // ids and thread ids, newest first, paged
    fn changes_since(cursor)             // the change log, or NeedsFullSync
    fn fetch_headers(ids)                // batched metadata
    fn fetch_body(id)                    // raw RFC 2822 bytes
    fn fetch_attachment(id, part)        // bytes
    fn set_flags(ids, seen, starred, archived, trashed, spam)
    fn labels() / apply_label / remove_label
    fn send(raw, thread_hint)            // returns the provider's id and thread id
    fn drafts(): create / update / delete
    fn search(query, page)               // provider-side search, ids only
    fn settings(): aliases, signature
}
```

Gmail implements it with the REST API. IMAP and SMTP will implement it next with folders mapped
onto the flag set and labels onto `X-GM-LABELS` or keywords, and JMAP after that with its own
change log. The trait is shaped by what every provider can do, and everything the trait cannot do
is done in the state database instead, which is why the state database exists.

Gmail specifics that live only inside the Gmail implementation: `history.list` as the change log
and its 404 recovery, the 6,000 units per minute per user budget, `format=metadata` with a fixed
header list for hydration, `format=raw` for bodies, batch requests of 25 to 50, truncated
exponential backoff on 429, threading rules on send, `CATEGORY_*` labels read as a hint for the
suggestion function, and the People API for contact autocomplete.

## Authentication and distribution

Loopback OAuth with PKCE from the calendar, unchanged: the consent page opens in the system
browser, never in a webview the app owns, and the code lands on `127.0.0.1`. Refresh tokens are
sealed with XChaCha20-Poly1305 in the app data directory as the calendar does, for the same
reasons (no `keyring` on Android, code-signature churn on macOS, no Secret Service on minimal
Linux). Scopes: `gmail.modify`, `gmail.settings.basic`, `contacts.other.readonly`,
`contacts.readonly`, and `calendar.events` for RSVP. No `mail.google.com` until IMAP is real.

Every Gmail scope that reads mail is restricted. The plan is the one in the research: push the
consent screen to production unverified for the friends release (100 lifetime users, no weekly
re-login), file restricted-scope verification at once with the statement that there is no server
and all Google user data stays on the device, ask in writing whether the security assessment
applies, and budget for it anyway. Bring-your-own OAuth client stays as an escape hatch in
settings for the technical.

## Sync

Polling, no push. `users.watch` needs a Pub/Sub subscription, which needs a server or an IAM
grant no desktop app should hold, and a relay is the thing that might drag the app into an
annual security assessment. `history.list` costs 2 units; polling every 12 seconds in the
foreground and 60 seconds in the background is a rounding error against the budget.

Initial sync is the expensive part after the May 2026 quota change: `messages.get` is 20 units,
so hydration runs at about 300 messages a minute per account. A 20,000 message mailbox takes
about an hour of background work; a 100,000 message mailbox most of a working day. The order is
newest first, the app is usable as soon as the first page lands, and a thin bar in the account
chip says how far back the mirror reaches. Bodies are fetched on open and prefetched for the
last 90 days when idle. Attachments are fetched on open and cached with a size cap. The mirror
is the whole mailbox by decision; a setting caps the age for people who want less on disk.

Every write is optimistic: it lands in the mirror, renders, and is pushed behind. Consecutive
flag changes are coalesced into `batchModify`. Offline writes queue in the outbox and drain on
reconnect, with the thread showing "Waiting to send" until a send goes.

Seen, starred, archived, trashed and spam are provider flags and go through the trait. Nothing in
the piles, the Screener, snoozes or notes ever touches the provider, so a user who screens out
two hundred senders makes zero API calls.

## The state journal and the backup store

The state database is written through an append-only journal: every change is an event with a
device id, a per-device sequence number, a wall-clock timestamp, a kind, a portable key, and a
payload. The tables are a materialised view of the journal. This is what makes roaming possible
without a server and what makes the backup meaningful.

A **backup store** is a trait with three operations: put a blob at a name, get a blob by name,
list names under a prefix. Two implementations ship: Google Drive's app-data folder, which every
Gmail user already has and which margin's backup already uses, and Cloudflare R2 through S3
credentials for people who run their own. Each device uploads its own journal segments under its
device id and downloads every other device's. Merging is last-writer-wins per key by timestamp,
which is correct for every kind of state here (a pile toggle, a note, a rule), and a device that
has been offline for a month simply replays what it missed.

Everything uploaded is encrypted on the device with XChaCha20-Poly1305 under a key that is
generated on first backup, stored sealed like the tokens, and shown once as a recovery phrase.
Drive and R2 hold ciphertext and names; neither can read a note or a rule. The recovery phrase is
the only way to attach a second device or restore after a lost one, and the settings panel says
so in one sentence.

Version one on macOS alone does not need the merge. The journal shape is there from the first
commit so that the iPhone can join without a migration.

## Security

Message bodies are parsed from raw RFC 2822 with a real MIME parser (`mail-parser`), never from
the provider's pre-parsed payload beyond headers, because encoded words, parameter
continuations and legacy charsets appear daily. HTML is sanitised in Rust before it reaches the
webview: scripts, forms, event handlers, `<meta>` refreshes, external stylesheets, `javascript:`
and `data:` navigation are removed; `cid:` references are rewritten to a local resource scheme;
every remote `<img>` is replaced with a placeholder and its source recorded. The body renders in
an iframe with a strict CSP inside the app's webview so the message can never touch the app.

Tracker stripping happens in the same pass: images with a known tracking host (a maintained
list, shipped with the app and updated with it), images of one pixel or hidden by style, and
images whose URL carries a recipient token are removed and counted, and the vendor is named in
the banner. When the user asks to show images, Rust fetches them without cookies or referrer and
serves them from cache; the user's IP is exposed to the image host at that moment and only then,
which the privacy setting says plainly. Outgoing mail never contains a tracker and the app never
requests a read receipt. Links are rewritten on click to drop known tracking parameters, with a
setting to turn that off.

Refresh tokens and the backup key are sealed, never in SQLite. The mirror and the state database
are files in the app data directory and inherit the OS's disk encryption; encrypting them again
would cost search and buy nothing on a device that is already locked, and the export path is
the answer for anyone who wants their mail in a form they control.

## Platforms

macOS: overlay title bar with the traffic lights on the header's centre line, closing the window
hides it and Cmd-Q quits, all from the calendar. iOS second: the same code with the phone chrome
from the calendar's `data-phone` and `data-touch` scheme, overlays as bottom sheets, the OAuth
flow through `ASWebAuthenticationSession`, and background app refresh used only to run the
snooze evaluation and a short sync. Linux afterwards: no traffic lights, closing quits, deb and
AppImage.

## Order of work

The sync engine and the reading pane are the two hard things and neither proves the other, so the
first milestone is one account, authentication, the mirror, and a read-only Inbox with a
sanitised, tracker-stripped reading pane. Everything the app is for depends on those being
right.

Second, triage on the mirror: seen, archive, star, trash, spam, selection, the keyboard, the
palette, local search. At this point it is a fast Gmail client and nothing more.

Third, the state database and the four places: sender rules, the suggestion function, the
Screener, the first-run pass, Feed and Paper Trail. This is the milestone where it stops being a
Gmail client.

Fourth, the piles and their friends: Reply later, Set aside, Focus & Reply, snooze with lazy
evaluation, notes, rename, merge, clips, All files, ignore, per-thread notifications, the contact
card.

Fifth, writing: reply, compose, drafts, the outbox with undo send, attachments, remind me if no
reply, instant intro, calendar RSVP.

Sixth, more than one account, the unified view, settings, export, and the backup store with the
journal behind it.

Then the iPhone, then Linux, then the IMAP provider, in that order.