# manikpruthi/mac-mail architecture

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

- Interactive diagram: https://gitdiagram.com/manikpruthi/mac-mail
- Repository: https://github.com/manikpruthi/mac-mail

## Overview

Mac Mail is a native macOS client whose central workflow is to open cached mail, synchronize account changes, and present messages for reading or action. The app delegate launches the three-pane interface; UI requests go through the app-wide mail service to per-account sync engines, network protocols, and the local store. Separate branches cover composing and queued sending, search, protected rendering, attachments, saved .eml messages, and settings. The README documents these capabilities; links among unsampled components are omitted unless supported by the source index or README.

Main entry points: [`Sources/Sync/MailService.swift`](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/MailService.swift) (Mail service), [`Sources/Sync/AccountEngine.swift`](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/AccountEngine.swift) (Account sync engine), [`Sources/UI/MainWindowController.swift`](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MainWindowController.swift) (Mail window), [`Sources/UI/PreviewViewController.swift`](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/PreviewViewController.swift) (Reading pane)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_ui["App and interface"]
  node_app["App lifecycle<br/>[AppDelegate.swift]"]
  node_main_window["Mail window"]
  node_sidebar["Folder sidebar"]
  node_message_list["Message list"]
  node_search_filters["Search filters"]
  node_settings["Account settings"]
  node_preview["Reading pane"]
  node_message_window["Message window"]
end

subgraph group_mail_content["Mail content"]
  node_composer["Composer"]
  node_format_bar["Format bar<br/>[FormatBar.swift]"]
  node_message_actions["Message actions"]
  node_render_prep["HTML protection<br/>[HTMLPrep.swift]"]
  node_image_loader["Image loading<br/>[ImageLoader.swift]"]
  node_attachments["Attachment handling"]
  node_eml_window["Saved message window"]
  node_eml_document["EML document<br/>[EMLDocument.swift]"]
  node_mime["MIME parsing<br/>[MIME.swift]"]
  node_mail_safety["Mail safety<br/>[MailSafety.swift]"]
  node_message_builder["Message builder"]
  node_search_query["Search query<br/>[SearchQuery.swift]"]
end

subgraph group_sync_network["Sync and network"]
  node_mail_service["Mail service<br/>[MailService.swift]"]
  node_account_engine["Account sync engine"]
  node_outbox["Offline outbox<br/>[Outbox.swift]"]
  node_imap["IMAP client<br/>[IMAPClient.swift]"]
  node_imap_parser["IMAP parser<br/>[IMAPParser.swift]"]
  node_smtp["SMTP client<br/>[SMTPClient.swift]"]
  node_tls["TLS stream<br/>[TLSStream.swift]"]
end

subgraph group_local_state["Local state"]
  node_store[("Offline mail store<br/>[Store.swift]")]
  node_sqlite[("SQLite layer<br/>[SQLite.swift]")]
  node_preferences["Preferences<br/>[Prefs.swift]"]
  node_keychain["Credential storage<br/>[Keychain.swift]"]
  node_diagnostics["Diagnostics log<br/>[Debug.swift]"]
end

subgraph group_external["External services"]
  node_imap_service(("IMAP account server"))
end

node_user(("Mail user"))

node_user -->|"launches"| node_app
node_app -->|"opens"| node_main_window
node_main_window -->|"hosts"| node_sidebar
node_main_window -->|"hosts"| node_message_list
node_main_window -->|"hosts"| node_preview
node_main_window -->|"opens"| node_message_window
node_main_window -->|"uses"| node_search_filters
node_app -->|"opens"| node_settings
node_message_list -->|"parses search"| node_search_query
node_search_filters -->|"builds filters"| node_search_query
node_message_list -->|"requests mail"| node_mail_service
node_sidebar -->|"requests folders"| node_mail_service
node_settings -->|"updates accounts"| node_mail_service
node_preview -->|"fetches messages"| node_mail_service
node_preview -->|"prepares HTML"| node_render_prep
node_preview -->|"loads images"| node_image_loader
node_preview -->|"shows attachments"| node_attachments
node_message_window -->|"embeds reader"| node_preview
node_message_window -->|"offers actions"| node_message_actions
node_message_window -->|"opens reply"| node_composer
node_main_window -->|"dispatches actions"| node_message_actions
node_composer -->|"uses formatting"| node_format_bar
node_composer -->|"sends messages"| node_mail_service
node_composer -->|"builds message"| node_message_builder
node_composer -->|"queues drafts"| node_outbox
node_eml_window -->|"opens document"| node_eml_document
node_eml_window -->|"uses reader"| node_preview
node_eml_window -->|"shows attachments"| node_attachments
node_mail_service -->|"manages engines"| node_account_engine
node_mail_service -->|"flushes queue"| node_outbox
node_account_engine -->|"updates cache"| node_store
node_account_engine -->|"synchronizes"| node_imap
node_account_engine -->|"sends mail"| node_smtp
node_account_engine -->|"reads credentials"| node_keychain
node_account_engine -->|"uses search"| node_search_query
node_account_engine -->|"builds outgoing mail"| node_message_builder
node_account_engine -->|"records errors"| node_diagnostics
node_imap -->|"parses responses"| node_imap_parser
node_imap -->|"uses transport"| node_tls
node_smtp -->|"uses transport"| node_tls
node_smtp -->|"checks content"| node_mail_safety
node_message_builder -->|"sanitizes headers"| node_mail_safety
node_mail_service -->|"owns cache"| node_store
node_store -->|"persists data"| node_sqlite
node_store -->|"runs local search"| node_search_query
node_mail_service -->|"loads settings"| node_preferences
node_imap -.->|"connects to"| node_imap_service
node_smtp -.->|"sends via account"| node_imap_service

click node_app "https://github.com/manikpruthi/mac-mail/blob/main/Sources/App/AppDelegate.swift"
click node_main_window "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MainWindowController.swift"
click node_sidebar "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SidebarViewController.swift"
click node_message_list "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageListViewController.swift"
click node_search_filters "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SearchFilterBar.swift"
click node_settings "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SettingsWindowController.swift"
click node_preview "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/PreviewViewController.swift"
click node_message_window "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageWindowController.swift"
click node_composer "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/ComposeWindowController.swift"
click node_format_bar "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/FormatBar.swift"
click node_message_actions "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageActions.swift"
click node_render_prep "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/HTMLPrep.swift"
click node_image_loader "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/ImageLoader.swift"
click node_attachments "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/AttachmentBar.swift"
click node_eml_window "https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/EMLWindowController.swift"
click node_eml_document "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/EMLDocument.swift"
click node_mime "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MIME.swift"
click node_mail_safety "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MailSafety.swift"
click node_message_builder "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MessageBuilder.swift"
click node_search_query "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/SearchQuery.swift"
click node_mail_service "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/MailService.swift"
click node_account_engine "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/AccountEngine.swift"
click node_outbox "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/Outbox.swift"
click node_imap "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/IMAPClient.swift"
click node_imap_parser "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/IMAPParser.swift"
click node_smtp "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/SMTPClient.swift"
click node_tls "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/TLSStream.swift"
click node_store "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Store.swift"
click node_sqlite "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/SQLite.swift"
click node_preferences "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Prefs.swift"
click node_keychain "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Keychain.swift"
click node_diagnostics "https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Debug.swift"

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_app,node_main_window,node_sidebar,node_message_list,node_search_filters,node_settings,node_preview,node_message_window,node_user toneBlue
class node_composer,node_format_bar,node_message_actions,node_render_prep,node_image_loader,node_attachments,node_eml_window,node_eml_document,node_mime,node_mail_safety,node_message_builder,node_search_query toneAmber
class node_mail_service,node_account_engine,node_outbox,node_imap,node_imap_parser,node_smtp,node_tls toneMint
class node_store,node_sqlite,node_preferences,node_keychain,node_diagnostics toneRose
class node_imap_service toneIndigo
```

## Components

### App and interface

- [App lifecycle](https://github.com/manikpruthi/mac-mail/blob/main/Sources/App/AppDelegate.swift): `Sources/App/AppDelegate.swift`
- [Mail window](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MainWindowController.swift): `Sources/UI/MainWindowController.swift`
- [Folder sidebar](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SidebarViewController.swift): `Sources/UI/SidebarViewController.swift`
- [Message list](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageListViewController.swift): `Sources/UI/MessageListViewController.swift`
- [Search filters](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SearchFilterBar.swift): `Sources/UI/SearchFilterBar.swift`
- [Account settings](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/SettingsWindowController.swift): `Sources/UI/SettingsWindowController.swift`
- [Reading pane](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/PreviewViewController.swift): `Sources/UI/PreviewViewController.swift`
- [Message window](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageWindowController.swift): `Sources/UI/MessageWindowController.swift`

### Mail content

- [Composer](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/ComposeWindowController.swift): `Sources/UI/ComposeWindowController.swift`
- [Format bar](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/FormatBar.swift): `Sources/UI/FormatBar.swift`
- [Message actions](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/MessageActions.swift): `Sources/UI/MessageActions.swift`
- [HTML protection](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/HTMLPrep.swift): `Sources/UI/HTMLPrep.swift`
- [Image loading](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/ImageLoader.swift): `Sources/UI/ImageLoader.swift`
- [Attachment handling](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/AttachmentBar.swift): `Sources/UI/AttachmentBar.swift`
- [Saved message window](https://github.com/manikpruthi/mac-mail/blob/main/Sources/UI/EMLWindowController.swift): `Sources/UI/EMLWindowController.swift`
- [EML document](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/EMLDocument.swift): `Sources/Mail/EMLDocument.swift`
- [MIME parsing](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MIME.swift): `Sources/Mail/MIME.swift`
- [Mail safety](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MailSafety.swift): `Sources/Mail/MailSafety.swift`
- [Message builder](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/MessageBuilder.swift): `Sources/Mail/MessageBuilder.swift`
- [Search query](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Mail/SearchQuery.swift): `Sources/Mail/SearchQuery.swift`

### Sync and network

- [Mail service](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/MailService.swift): `Sources/Sync/MailService.swift`
- [Account sync engine](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/AccountEngine.swift): `Sources/Sync/AccountEngine.swift`
- [Offline outbox](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Sync/Outbox.swift): `Sources/Sync/Outbox.swift`
- [IMAP client](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/IMAPClient.swift): `Sources/Net/IMAPClient.swift`
- [IMAP parser](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/IMAPParser.swift): `Sources/Net/IMAPParser.swift`
- [SMTP client](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/SMTPClient.swift): `Sources/Net/SMTPClient.swift`
- [TLS stream](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Net/TLSStream.swift): `Sources/Net/TLSStream.swift`

### Local state

- [Offline mail store](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Store.swift): `Sources/Core/Store.swift`
- [SQLite layer](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/SQLite.swift): `Sources/Core/SQLite.swift`
- [Preferences](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Prefs.swift): `Sources/Core/Prefs.swift`
- [Credential storage](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Keychain.swift): `Sources/Core/Keychain.swift`
- [Diagnostics log](https://github.com/manikpruthi/mac-mail/blob/main/Sources/Core/Debug.swift): `Sources/Core/Debug.swift`

### External services

- **IMAP account server**

### Other components

- **Mail user**

## Connections

- Mail user → App lifecycle: launches (evidence: `Sources/App/AppDelegate.swift`)
- App lifecycle → Mail window: opens (evidence: `Sources/App/AppDelegate.swift`)
- Mail window → Folder sidebar: hosts (evidence: `Sources/UI/MainWindowController.swift`)
- Mail window → Message list: hosts (evidence: `Sources/UI/MainWindowController.swift`)
- Mail window → Reading pane: hosts (evidence: `Sources/UI/MainWindowController.swift`)
- Mail window → Message window: opens (evidence: `Sources/UI/MainWindowController.swift`)
- Mail window → Search filters: uses (evidence: `Sources/UI/MainWindowController.swift`)
- App lifecycle → Account settings: opens (evidence: `Sources/App/AppDelegate.swift`)
- Message list → Search query: parses search (evidence: `Sources/UI/MessageListViewController.swift`)
- Search filters → Search query: builds filters (evidence: `Sources/UI/SearchFilterBar.swift`)
- Message list → Mail service: requests mail (evidence: `Sources/UI/MessageListViewController.swift`)
- Folder sidebar → Mail service: requests folders (evidence: `Sources/UI/SidebarViewController.swift`)
- Account settings → Mail service: updates accounts (evidence: `Sources/UI/SettingsWindowController.swift`)
- Reading pane → Mail service: fetches messages (evidence: `Sources/UI/PreviewViewController.swift`)
- Reading pane → HTML protection: prepares HTML (evidence: `Sources/UI/PreviewViewController.swift`)
- Reading pane → Image loading: loads images (evidence: `Sources/UI/PreviewViewController.swift`)
- Reading pane → Attachment handling: shows attachments (evidence: `Sources/UI/PreviewViewController.swift`)
- Message window → Reading pane: embeds reader (evidence: `Sources/UI/MessageWindowController.swift`)
- Message window → Message actions: offers actions (evidence: `Sources/UI/MessageWindowController.swift`)
- Message window → Composer: opens reply (evidence: `Sources/UI/MessageWindowController.swift`)
- Mail window → Message actions: dispatches actions (evidence: `Sources/UI/MainWindowController.swift`)
- Composer → Format bar: uses formatting (evidence: `Sources/UI/ComposeWindowController.swift`)
- Composer → Mail service: sends messages (evidence: `Sources/UI/ComposeWindowController.swift`)
- Composer → Message builder: builds message (evidence: `Sources/UI/ComposeWindowController.swift`)
- Composer → Offline outbox: queues drafts (evidence: `Sources/UI/ComposeWindowController.swift`)
- Saved message window → EML document: opens document (evidence: `Sources/UI/EMLWindowController.swift`)
- Saved message window → Reading pane: uses reader (evidence: `Sources/UI/EMLWindowController.swift`)
- Saved message window → Attachment handling: shows attachments (evidence: `Sources/UI/EMLWindowController.swift`)
- Mail service → Account sync engine: manages engines (evidence: `Sources/Sync/MailService.swift`)
- Mail service → Offline outbox: flushes queue (evidence: `Sources/Sync/MailService.swift`)
- Account sync engine → Offline mail store: updates cache (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → IMAP client: synchronizes (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → SMTP client: sends mail (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → Credential storage: reads credentials (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → Search query: uses search (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → Message builder: builds outgoing mail (evidence: `Sources/Sync/AccountEngine.swift`)
- Account sync engine → Diagnostics log: records errors (evidence: `Sources/Sync/AccountEngine.swift`)
- IMAP client → IMAP parser: parses responses (evidence: `Sources/Net/IMAPClient.swift`)
- IMAP client → TLS stream: uses transport (evidence: `Sources/Net/IMAPClient.swift`)
- SMTP client → TLS stream: uses transport (evidence: `Sources/Net/SMTPClient.swift`)
- SMTP client → Mail safety: checks content (evidence: `Sources/Net/SMTPClient.swift`)
- Message builder → Mail safety: sanitizes headers (evidence: `Sources/Mail/MessageBuilder.swift`)
- Mail service → Offline mail store: owns cache (evidence: `Sources/Sync/MailService.swift`)
- Offline mail store → SQLite layer: persists data (evidence: `Sources/Core/Store.swift`)
- Offline mail store → Search query: runs local search (evidence: `Sources/Core/Store.swift`)
- Mail service → Preferences: loads settings (evidence: `Sources/Sync/MailService.swift`)
- IMAP client → IMAP account server: connects to
- SMTP client → IMAP account server: sends via account
