How ankitvgupta/mail-app works
1. Product shape and runtime
- Exo is a macOS desktop email client built as an Electron app with a React/TypeScript renderer.
- The app is split into the classic Electron boundaries: main process for privileged work, preload for a safe bridge, and renderer for UI.
2. Top-level architectural split
- src/main owns external integrations, local persistence, background automation, AI orchestration, and extension hosting.
- src/renderer owns inbox, compose, settings, sidebar panels, and all interactive UI.
- src/shared contains cross-process types and utilities so main and renderer stay schema-aligned.
3. Data and persistence boundary
- Local state is centered in src/main/db plus services around sync, memory, drafts, snooze, pending actions, and cached analysis.
- The app persists configuration and operational data under the user application support directory, and uses local database-backed stores for inbox state, learned preferences, and queued actions.
4. Email sync and inbox pipeline
- Gmail is the primary external system. gmail-client, email-sync, background-sync, and gmail-draft-sync handle fetching, incremental history sync, and write-back of changes.
- Incoming mail is normalized, analyzed, categorized, and then surfaced to the renderer via IPC. The renderer mostly consumes the synced local model rather than talking directly to Gmail.
5. AI/LLM orchestration
- AI features are concentrated in src/main/services and src/main/agents.
- anthropic-service, email-analyzer, draft-generator, draft-pipeline, archive-ready-analyzer, and calendaring-agent implement background classification, draft creation, archive readiness, and scheduling detection.
- These services feed learned outputs back into local memory and UI state, so AI is not just a one-shot request layer.
6. Agent system and tool execution
- The agent subsystem is its own orchestration layer: agent-coordinator, agent-worker, orchestrator, permission-gate, and audit-log.
- Tools are registered separately under src/main/agents/tools and include analysis, browser, email, context, and sub-agent delegation.
- Provider abstraction lives in src/main/agents/providers, allowing the built-in Claude agent to delegate to remote or extension-provided agent providers.
7. Extension architecture
- Extensions are first-class and split into bundled, private, and runtime-installable variants.
- Main-process extension hosting and manifests live under src/main/extensions; renderer-side UI slots and extension panels live under src/renderer/extensions.
- Extension APIs are designed to let add-ons contribute sidebar panels, auth requirements, and even agent providers, while still being mediated by the main process.
8. UI composition and IPC flow
- The renderer is a feature-rich client: inbox views, compose editor, agent palette, search, settings, memories, snooze, splits, and update banners.
- Renderer components call into src/main/ipc/* endpoints for privileged actions such as Gmail operations, drafts, settings, memory, sync, calendar, attachments, and agents.
- preload is the narrow bridge that exposes these capabilities safely to the React app.
9. Compose and send pipeline
- Compose is not just a form: it includes rich text editing, recipient autocomplete, signatures, inline reply, attachments, scheduling, and undo-send.
- On the main side, draft-pipeline, scheduled-send-service, outbox-service, pending-actions, and draft-edit-learner manage generation, delayed delivery, offline queuing, and learning from user edits.
- This means send operations are staged and reversible, with renderer optimism backed by main-process reconciliation.
10. Search, triage, and inbox organization
- Search uses a hybrid model: local full-text search plus Gmail API search for completeness.
- Inbox organization is driven by AI and rules: priority splits, archive-ready threads, snoozed mail, sent mail, and custom split tabs.
- The renderer treats these as views over the synced model; the main process owns the categorization logic and persistence.
11. Memory and personalization loop
- memory-context, memory-learner-utils, priority override learning, style indexing/profiling, and draft-edit learning form a feedback loop.
- User actions in the renderer become signals that are stored and later injected into AI prompts or categorization decisions.
- This is a core architectural theme: user behavior is converted into durable preference data in the main process.
12. Calendar and external context
- Calendar sync is separate from mail sync and handled by dedicated services plus a calendar extension package.
- Calendar data is surfaced as a sidebar view and also used by scheduling-related agent behavior and executive-assistant style automation.
- The calendar subsystem is another example of the app aggregating multiple external data sources into one local model.
13. Offline, resilience, and background work
- network-monitor, network-errors, prefetch-service, background-sync, and pending-actions support offline-aware behavior and deferred execution.
- The app emphasizes optimistic UI with rollback, cached HTML/email bodies, and background batching to keep navigation smooth while sync continues.
14. Testing and validation architecture
- The repo has a strong test split: unit tests for services and utilities, integration tests for cross-cutting flows, end-to-end Playwright tests for UI behavior, and evals for AI quality.
- tests/evals and the supporting scripts indicate that AI behavior is treated as a product surface with scoring and regression checks, not just ordinary unit coverage.
15. Build and deployment
- Build tooling is Electron/Vite-based, with separate configs for web, main, and worker targets.
- CI and release workflows package the macOS app, and the presence of entitlements/plists indicates native macOS signing/notarization concerns are part of the deployment boundary.
16. Overall architectural diagram takeaway
- The central shape is: Gmail and Anthropic plus optional extensions/providers on the outside; Electron main as the orchestration and integration hub; the React renderer as the presentation layer; shared types and IPC as the contract between them.
- Most “smart” behavior lives in main-process services and agent orchestration, while the renderer remains a reactive client over synced local state and privileged actions.
Main entry points: ipc IPC layer · App.tsx App shell · anthropic-service.ts AI services · index.ts Main entry
Components 22
Main process
Privileged Electron orchestration, sync, persistence, AI, and integrations.
- Main entry · Starts the app and wires core Electron lifecycle.
src/main/index.ts - IPC layer · Privileged endpoints for renderer-initiated operations.
src/main/ipc - Sync services · Fetches, normalizes, and reconciles Gmail state locally.
src/main/services/email-sync.ts - Local DB · Database-backed inbox state, queued actions, and durable app data.
src/main/db - Draft pipeline · Generates, edits, stages, schedules, and syncs outgoing mail.
src/main/services/draft-pipeline.ts - AI services · Classification, generation, archive readiness, memory, and scheduling intelligence.
src/main/services/anthropic-service.ts - Agent system · Agent coordination, workers, permissions, audit, tools, and providers.
src/main/agents - Extension host · Loads manifests, hosts extension code, and mediates extension capabilities.
src/main/extensions
Renderer
React UI and feature views for the mailbox client.
- App shell · Top-level renderer composition and state wiring.
src/renderer/App.tsx - Inbox UI · Inbox lists, message detail, search, splits, snooze, and batch actions.
src/renderer/components/EmailList.tsx - Compose UI · Rich text compose, reply, attachments, signatures, autocomplete, and send controls.
src/renderer/components/ComposeEditor.tsx - Settings panel · Configuration, onboarding, and app-level settings surfaces.
src/renderer/components/SettingsPanel.tsx - Agent UI · Agent palette, confirmations, sidebar panels, and related controls.
src/renderer/components/AgentPanel.tsx - Extension UI · Renderer-side extension panels and bundled extension surfaces.
src/renderer/extensions - Client state · Renderer store, optimistic reads, and local presentation state.
src/renderer/store
Shared
Cross-process types and reusable utilities.
- Shared contracts · Cross-process schemas, shared draft helpers, and common utilities.
src/shared/types.ts
Extensions
Bundled and installable extension host and extension UIs.
- Calendar ext · Calendar provider and panel packaged as an extension.
src/extensions/mail-ext-calendar/src/index.ts - Web search ext · Web search provider extension used by the agent ecosystem.
src/extensions/mail-ext-web-search/src/index.ts
Tests
Unit, integration, end-to-end, and eval coverage.
- Unit tests · Focused coverage for services, utilities, and domain logic.
tests/unit - E2E tests · End-to-end user flows, UI behavior, and screenshot coverage.
tests/e2e - AI evals · Model behavior fixtures, scoring, and regression evaluation.
tests/evals
Build
Electron/Vite packaging, release, and native app deployment.
- Build & release · Electron-Vite configs, workflows, native signing, and release packaging.
electron-vite.config.ts
Connections 38
- Main entry → IPC layer: registers · Bootstraps the IPC surface for renderer requests.
- Main entry → Sync services: starts · Initializes background mail synchronization.
- Main entry → Local DB: opens · Connects the app to local persistent state.
- Main entry → Extension host: loads · Starts the extension host during application startup.
- App shell → Inbox UI: composes · Renders mailbox and thread views.
- App shell → Compose UI: composes · Mounts the compose and reply workflow.
- App shell → Settings panel: composes · Shows settings and onboarding surfaces.
- App shell → Agent UI: composes · Surfaces agent controls and confirmations.
- App shell → Extension UI: composes · Hosts extension panels in the UI.
- App shell → Client state: uses · Reads and updates client-side presentation state.
- Inbox UI → IPC layer: queries · Fetches inbox data and triggers privileged mail actions.
- Compose UI → IPC layer: sends · Creates drafts, attachments, and send operations via IPC.
- Settings panel → IPC layer: updates · Reads and writes app settings through the bridge.
- Agent UI → IPC layer: delegates · Requests agent execution and approvals from main.
- Extension UI → IPC layer: invokes · Calls extension-mediated privileged actions.
- IPC layer → Sync services: controls · Exposes sync and Gmail actions to the renderer.
- IPC layer → Draft pipeline: controls · Exposes compose, draft, and send pipeline operations.
- IPC layer → AI services: controls · Exposes analysis, memory, and scheduling services.
- IPC layer → Agent system: controls · Exposes agent orchestration and tool execution.
- IPC layer → Extension host: controls · Exposes extension APIs and manifests to the UI.
- Sync services → Local DB: persists · Stores synced mail and derived inbox state locally.
- Sync services → AI services: feeds · Sends normalized mail into classification and analysis.
- Draft pipeline → Local DB: persists · Stores draft, outbox, and queued send state.
- Draft pipeline → AI services: learns from · Uses AI generation and edit learning.
- AI services → Local DB: writes back · Materializes memories, profiles, and learned preferences.
- Agent system → AI services: uses · Consumes LLM services for agent reasoning and delegation.
- Extension host → Calendar ext: hosts · Loads the bundled calendar extension.
- Extension host → Web search ext: hosts · Loads the bundled web search extension.
- Extension UI → Calendar ext: renders · Shows the calendar panel contributed by the extension.
- AI services → Shared contracts: shares · Uses shared schemas for prompts, drafts, and results.
- IPC layer → Shared contracts: validates · Keeps renderer/main contracts aligned.
- Client state → Shared contracts: reads · Uses shared types for client state shape.
- Unit tests → AI services: covers · Exercises AI and service logic.
- Unit tests → Sync services: covers · Verifies sync and persistence behavior.
- E2E tests → App shell: covers · Validates user-facing flows and UI interactions.
- AI evals → AI services: scores · Measures draft and classification quality.
- Build & release → Main entry: packages · Builds the Electron main process and app shell.
- Build & release → App shell: bundles · Builds the renderer application assets.