# ankitvgupta/mail-app architecture

> Architecture diagram of the GitHub repository ankitvgupta/mail-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankitvgupta/mail-app
- Repository: https://github.com/ankitvgupta/mail-app

## Overview

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: [`src/main/ipc`](https://github.com/ankitvgupta/mail-app/tree/main/src/main/ipc) (IPC layer), [`src/renderer/App.tsx`](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/App.tsx) (App shell), [`src/main/services/anthropic-service.ts`](https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/anthropic-service.ts) (AI services), [`src/main/index.ts`](https://github.com/ankitvgupta/mail-app/blob/main/src/main/index.ts) (Main entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_main["Main process"]
  node_n_main_entry["Main entry<br/>electron bootstrap<br/>[index.ts]"]
  node_n_main_ipc["IPC layer<br/>command bridge"]
  node_n_main_sync["Sync services<br/>gmail sync<br/>[email-sync.ts]"]
  node_n_main_db[("Local DB<br/>persistence")]
  node_n_main_drafts["Draft pipeline<br/>compose workflow<br/>[draft-pipeline.ts]"]
  node_n_main_ai["AI services<br/>llm orchestration"]
  node_n_main_agents["Agent system<br/>agent orchestration"]
  node_n_main_extensions["Extension host<br/>extension runtime"]
end

subgraph group_g_renderer["Renderer"]
  node_n_renderer_app["App shell<br/>react shell<br/>[App.tsx]"]
  node_n_renderer_inbox["Inbox UI<br/>mail views<br/>[EmailList.tsx]"]
  node_n_renderer_compose["Compose UI<br/>editor workflow<br/>[ComposeEditor.tsx]"]
  node_n_renderer_settings["Settings panel<br/>preferences ui<br/>[SettingsPanel.tsx]"]
  node_n_renderer_agents["Agent UI<br/>assistant ui<br/>[AgentPanel.tsx]"]
  node_n_renderer_extensions["Extension UI<br/>extension slots"]
  node_n_renderer_store["Client state<br/>ui state"]
end

subgraph group_g_shared["Shared"]
  node_n_shared_types["Shared contracts<br/>types and utils<br/>[types.ts]"]
end

subgraph group_g_extensions["Extensions"]
  node_n_ext_calendar["Calendar ext<br/>bundled extension<br/>[index.ts]"]
  node_n_ext_web["Web search ext<br/>bundled extension<br/>[index.ts]"]
end

subgraph group_g_tests["Tests"]
  node_n_tests_unit["Unit tests<br/>service tests"]
  node_n_tests_e2e["E2E tests<br/>playwright ui"]
  node_n_tests_evals["AI evals<br/>quality evals"]
end

subgraph group_g_build["Build"]
  node_n_build["Build & release<br/>packaging"]
end

node_n_main_entry -->|"registers"| node_n_main_ipc
node_n_main_entry -->|"starts"| node_n_main_sync
node_n_main_entry -->|"opens"| node_n_main_db
node_n_main_entry -->|"loads"| node_n_main_extensions
node_n_renderer_app -->|"composes"| node_n_renderer_inbox
node_n_renderer_app -->|"composes"| node_n_renderer_compose
node_n_renderer_app -->|"composes"| node_n_renderer_settings
node_n_renderer_app -->|"composes"| node_n_renderer_agents
node_n_renderer_app -->|"composes"| node_n_renderer_extensions
node_n_renderer_app -->|"uses"| node_n_renderer_store
node_n_renderer_inbox -->|"queries"| node_n_main_ipc
node_n_renderer_compose -->|"sends"| node_n_main_ipc
node_n_renderer_settings -->|"updates"| node_n_main_ipc
node_n_renderer_agents -->|"delegates"| node_n_main_ipc
node_n_renderer_extensions -->|"invokes"| node_n_main_ipc
node_n_main_ipc -->|"controls"| node_n_main_sync
node_n_main_ipc -->|"controls"| node_n_main_drafts
node_n_main_ipc -->|"controls"| node_n_main_ai
node_n_main_ipc -->|"controls"| node_n_main_agents
node_n_main_ipc -->|"controls"| node_n_main_extensions
node_n_main_sync -->|"persists"| node_n_main_db
node_n_main_sync -->|"feeds"| node_n_main_ai
node_n_main_drafts -->|"persists"| node_n_main_db
node_n_main_drafts -->|"learns from"| node_n_main_ai
node_n_main_ai -->|"writes back"| node_n_main_db
node_n_main_agents -->|"uses"| node_n_main_ai
node_n_main_extensions -->|"hosts"| node_n_ext_calendar
node_n_main_extensions -->|"hosts"| node_n_ext_web
node_n_renderer_extensions -->|"renders"| node_n_ext_calendar
node_n_main_ai -->|"shares"| node_n_shared_types
node_n_main_ipc -->|"validates"| node_n_shared_types
node_n_renderer_store -->|"reads"| node_n_shared_types
node_n_tests_unit -.->|"covers"| node_n_main_ai
node_n_tests_unit -.->|"covers"| node_n_main_sync
node_n_tests_e2e -.->|"covers"| node_n_renderer_app
node_n_tests_evals -.->|"scores"| node_n_main_ai
node_n_build -->|"packages"| node_n_main_entry
node_n_build -->|"bundles"| node_n_renderer_app

click node_n_main_entry "https://github.com/ankitvgupta/mail-app/blob/main/src/main/index.ts"
click node_n_main_ipc "https://github.com/ankitvgupta/mail-app/tree/main/src/main/ipc"
click node_n_main_sync "https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/email-sync.ts"
click node_n_main_db "https://github.com/ankitvgupta/mail-app/tree/main/src/main/db"
click node_n_main_drafts "https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/draft-pipeline.ts"
click node_n_main_ai "https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/anthropic-service.ts"
click node_n_main_agents "https://github.com/ankitvgupta/mail-app/tree/main/src/main/agents"
click node_n_main_extensions "https://github.com/ankitvgupta/mail-app/tree/main/src/main/extensions"
click node_n_renderer_app "https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/App.tsx"
click node_n_renderer_inbox "https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/EmailList.tsx"
click node_n_renderer_compose "https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/ComposeEditor.tsx"
click node_n_renderer_settings "https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/SettingsPanel.tsx"
click node_n_renderer_agents "https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/AgentPanel.tsx"
click node_n_renderer_extensions "https://github.com/ankitvgupta/mail-app/tree/main/src/renderer/extensions"
click node_n_renderer_store "https://github.com/ankitvgupta/mail-app/tree/main/src/renderer/store"
click node_n_shared_types "https://github.com/ankitvgupta/mail-app/blob/main/src/shared/types.ts"
click node_n_ext_calendar "https://github.com/ankitvgupta/mail-app/blob/main/src/extensions/mail-ext-calendar/src/index.ts"
click node_n_ext_web "https://github.com/ankitvgupta/mail-app/blob/main/src/extensions/mail-ext-web-search/src/index.ts"
click node_n_tests_unit "https://github.com/ankitvgupta/mail-app/tree/main/tests/unit"
click node_n_tests_e2e "https://github.com/ankitvgupta/mail-app/tree/main/tests/e2e"
click node_n_tests_evals "https://github.com/ankitvgupta/mail-app/tree/main/tests/evals"
click node_n_build "https://github.com/ankitvgupta/mail-app/blob/main/electron-vite.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_main_entry,node_n_main_ipc,node_n_main_sync,node_n_main_db,node_n_main_drafts,node_n_main_ai,node_n_main_agents,node_n_main_extensions toneBlue
class node_n_renderer_app,node_n_renderer_inbox,node_n_renderer_compose,node_n_renderer_settings,node_n_renderer_agents,node_n_renderer_extensions,node_n_renderer_store toneAmber
class node_n_shared_types toneMint
class node_n_ext_calendar,node_n_ext_web toneRose
class node_n_tests_unit,node_n_tests_e2e,node_n_tests_evals toneIndigo
class node_n_build toneTeal
```

## Components

### Main process

Privileged Electron orchestration, sync, persistence, AI, and integrations.

- [Main entry](https://github.com/ankitvgupta/mail-app/blob/main/src/main/index.ts): electron bootstrap · Starts the app and wires core Electron lifecycle. · `src/main/index.ts`
- [IPC layer](https://github.com/ankitvgupta/mail-app/tree/main/src/main/ipc): command bridge · Privileged endpoints for renderer-initiated operations. · `src/main/ipc`
- [Sync services](https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/email-sync.ts): gmail sync · Fetches, normalizes, and reconciles Gmail state locally. · `src/main/services/email-sync.ts`
- [Local DB](https://github.com/ankitvgupta/mail-app/tree/main/src/main/db): persistence · Database-backed inbox state, queued actions, and durable app data. · `src/main/db`
- [Draft pipeline](https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/draft-pipeline.ts): compose workflow · Generates, edits, stages, schedules, and syncs outgoing mail. · `src/main/services/draft-pipeline.ts`
- [AI services](https://github.com/ankitvgupta/mail-app/blob/main/src/main/services/anthropic-service.ts): llm orchestration · Classification, generation, archive readiness, memory, and scheduling intelligence. · `src/main/services/anthropic-service.ts`
- [Agent system](https://github.com/ankitvgupta/mail-app/tree/main/src/main/agents): agent orchestration · Agent coordination, workers, permissions, audit, tools, and providers. · `src/main/agents`
- [Extension host](https://github.com/ankitvgupta/mail-app/tree/main/src/main/extensions): extension runtime · Loads manifests, hosts extension code, and mediates extension capabilities. · `src/main/extensions`

### Renderer

React UI and feature views for the mailbox client.

- [App shell](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/App.tsx): react shell · Top-level renderer composition and state wiring. · `src/renderer/App.tsx`
- [Inbox UI](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/EmailList.tsx): mail views · Inbox lists, message detail, search, splits, snooze, and batch actions. · `src/renderer/components/EmailList.tsx`
- [Compose UI](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/ComposeEditor.tsx): editor workflow · Rich text compose, reply, attachments, signatures, autocomplete, and send controls. · `src/renderer/components/ComposeEditor.tsx`
- [Settings panel](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/SettingsPanel.tsx): preferences ui · Configuration, onboarding, and app-level settings surfaces. · `src/renderer/components/SettingsPanel.tsx`
- [Agent UI](https://github.com/ankitvgupta/mail-app/blob/main/src/renderer/components/AgentPanel.tsx): assistant ui · Agent palette, confirmations, sidebar panels, and related controls. · `src/renderer/components/AgentPanel.tsx`
- [Extension UI](https://github.com/ankitvgupta/mail-app/tree/main/src/renderer/extensions): extension slots · Renderer-side extension panels and bundled extension surfaces. · `src/renderer/extensions`
- [Client state](https://github.com/ankitvgupta/mail-app/tree/main/src/renderer/store): ui state · Renderer store, optimistic reads, and local presentation state. · `src/renderer/store`

### Shared

Cross-process types and reusable utilities.

- [Shared contracts](https://github.com/ankitvgupta/mail-app/blob/main/src/shared/types.ts): types and utils · Cross-process schemas, shared draft helpers, and common utilities. · `src/shared/types.ts`

### Extensions

Bundled and installable extension host and extension UIs.

- [Calendar ext](https://github.com/ankitvgupta/mail-app/blob/main/src/extensions/mail-ext-calendar/src/index.ts): bundled extension · Calendar provider and panel packaged as an extension. · `src/extensions/mail-ext-calendar/src/index.ts`
- [Web search ext](https://github.com/ankitvgupta/mail-app/blob/main/src/extensions/mail-ext-web-search/src/index.ts): bundled extension · 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](https://github.com/ankitvgupta/mail-app/tree/main/tests/unit): service tests · Focused coverage for services, utilities, and domain logic. · `tests/unit`
- [E2E tests](https://github.com/ankitvgupta/mail-app/tree/main/tests/e2e): playwright ui · End-to-end user flows, UI behavior, and screenshot coverage. · `tests/e2e`
- [AI evals](https://github.com/ankitvgupta/mail-app/tree/main/tests/evals): quality evals · Model behavior fixtures, scoring, and regression evaluation. · `tests/evals`

### Build

Electron/Vite packaging, release, and native app deployment.

- [Build & release](https://github.com/ankitvgupta/mail-app/blob/main/electron-vite.config.ts): packaging · Electron-Vite configs, workflows, native signing, and release packaging. · `electron-vite.config.ts`

## Connections

- 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.
