Architecture
mxr is a local mail runtime. Its clients share daemon-backed mail operations over a local store, search index and provider adapters.
The short version
Section titled “The short version”TUI / CLI / web / MCP / scripts | v daemon / | \ SQLite Tantivy provider adapters canonical rebuildable | v mail providersThe daemon coordinates shared local mail state and operations. SQLite is canonical; Tantivy is rebuildable from it. Provider adapters map provider mail into mxr’s internal model and handle provider I/O. Clients can reuse daemon operations without duplicating provider behavior, while exposing different capabilities and authority.
IPC buckets
Section titled “IPC buckets”mxr keeps one flat IPC wire format, but the contract is easier to maintain if you sort it mentally into four buckets:
core-mailmxr-platformadmin-maintenanceclient-specific
Only the first three belong in daemon IPC.
core-mail: search, sync, envelopes, bodies, threads, labels, drafts, send, mutations, attachments, exportmxr-platform: accounts, rules, saved searches, subscriptions, semantic runtimeadmin-maintenance: status, events, logs, doctor, bug reports, local reset, repair/inspectionclient-specific: sidebar grouping, pane state, right-rail shaping, selection state; keep this in TUI/web/CLI layers
The daemon serves reusable truth and workflows, not screen payloads.
Why it is shaped this way
Section titled “Why it is shaped this way”Local-first
Section titled “Local-first”Mail should stay useful when the network is flaky, when you want to script against it, and when you do not want another hosted layer in the middle.
Daemon-backed
Section titled “Daemon-backed”The TUI should not be the whole system. Background sync, indexing, snooze, and rules should keep running without an open UI.
One model in the middle
Section titled “One model in the middle”Gmail labels, IMAP folders, flags, drafts, and bodies all have to meet the same internal model. That is what keeps the rest of the codebase sane.
Search as navigation
Section titled “Search as navigation”Search is not a fallback. It is how power users move through a mailbox. That is why mxr uses Tantivy and saved searches instead of treating search as an afterthought.
$EDITOR for writing
Section titled “$EDITOR for writing”Compose opens the editor you already use. mxr handles parsing, reply headers, markdown-to-multipart conversion, and sending.
Principles
Section titled “Principles”- Local-first
- Provider-agnostic internal model
- Daemon-backed architecture
$EDITORfor writing- Fast search is first-class
- Saved searches are a core primitive
- Rules are deterministic first
- Shell hooks over plugin systems
- Adapters are swappable
- Correctness beats cleverness
Read more
Section titled “Read more”- Root summary: ARCHITECTURE.md
- Full blueprint: docs/blueprint/README.md
Stored asks share one answer across clients
Section titled “Stored asks share one answer across clients”The deterministic asks facet covers received and sent mail. It stores who acts, what they were asked to do, document state and authored source spans. To do, reply turns, waits and relationship commitments project that answer. Home placement remains an inbound-only facet; both facets commit under the same thread-generation check. Missing or stale asks stay pending. No model decides this facet.
Inspect the stored answer and a task projected from it:
mxr modes why MESSAGE_ID --format jsonmxr todo why TODO_ID --format jsonAn answer is current only for its account, classifier policy, observed input generation and context. Owned addresses, actual timezone rules and account receiver-trust settings also participate in asks validity. Changing those inputs schedules reconciliation. An unchanged daemon restart retains settled answers without invalidating the whole mailbox.
Saving an answer also persists its task-projection retry ticket. Acknowledging that ticket checks the exact generation and fingerprint, so an older worker cannot consume newer work. Evaluation distinguishes unsettled projection from a settled answer with a missing task. Current-answer reads do not run a replacement judge.
Task corrections retain their reason and before/after state separately from the authored source quote. A later accepted promise date can update the date and its derived timing while preserving a corrected title or kind. If you edited the due date directly on the task, that authority blocks the entire promise-date update, including its derived timing.
Lists read compact facts; detail keeps the evidence
Section titled “Lists read compact facts; detail keeps the evidence”Compare the list and detail surfaces:
mxr messages list --turn all --format jsonmxr messages person samir@launchpad.example --format jsonmxr modes why MESSAGE_ID --format jsonLists use compact, rebuildable asks and thread facts, so navigation does not decode every stored body or full classification explanation. Opening a conversation or inspecting a placement reads the full source evidence. List previews read a bounded set of stored body text and skip attachment metadata.
Before it reuses thread facts, mxr checks the account, policy, input and view revisions, context and time boundaries. Read flags, inbox membership and facet writes invalidate thread facts even when the source generation is unchanged. Turns, Done state, people links, contact facts, ranking and filters are always composed live.
A separate short-lived daemon cache reuses completed mode responses. That cache does not hold these facts. For measurement and isolated invalidation checks, use the repository’s local mail-view procedure.