# floatpane/matcha architecture

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

- Interactive diagram: https://gitdiagram.com/floatpane/matcha
- Repository: https://github.com/floatpane/matcha

## Overview

Matcha is a terminal email client. The main workflow starts at the CLI, launches the Bubble Tea application, fetches mail for configured accounts, and presents inbox and message views; users can then search, act on messages, or compose and send mail. A daemon-backed service mediates mailbox operations, with direct-provider fallback. Other documented or indexed capabilities include plugins and their marketplace, rich email rendering, export, encryption, and the optional macOS menu-bar helper. Some subsystem links are omitted where sampled sources do not show their runtime wiring.

Main entry points: [`app/app.go`](https://github.com/floatpane/matcha/blob/master/app/app.go) (Application model), [`backend/backend.go`](https://github.com/floatpane/matcha/blob/master/backend/backend.go) (Provider interface), [`tui/email_view.go`](https://github.com/floatpane/matcha/blob/master/tui/email_view.go) (Message view), [`daemonclient/service.go`](https://github.com/floatpane/matcha/blob/master/daemonclient/service.go) (Mailbox service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal client"]
  node_cli["CLI entry<br/>[main.go]"]
  node_application["Application model<br/>[app.go]"]
  node_inbox["Inbox and views<br/>[inbox.go]"]
  node_search["Mail search<br/>[search.go]"]
  node_emailview["Message view<br/>[email_view.go]"]
end

subgraph group_mail["Mail operations"]
  node_actions["Message actions<br/>[manager.go]"]
  node_fetcher["Fetch and search<br/>[fetcher.go]"]
  node_service["Mailbox service<br/>[service.go]"]
  node_daemon["Mailbox daemon<br/>[handler.go]"]
  node_protocol["Provider interface<br/>[backend.go]"]
  node_jmap["JMAP provider<br/>[jmap.go]"]
  node_maildir["Maildir provider<br/>[maildir.go]"]
  node_pop3["POP3 provider<br/>[pop3.go]"]
  node_sender["Message sending<br/>[sender.go]"]
  node_export["Mail export<br/>[export.go]"]
end

subgraph group_extensions["Plugins and extensions"]
  node_plugins["Plugin runtime<br/>[plugin.go]"]
  node_pluginbridge["TUI plugin bridge<br/>[manager.go]"]
  node_marketplace["Plugin marketplace<br/>[client.go]"]
  node_pluginstore[("Plugin storage<br/>[storage.go]")]
end

subgraph group_support["Rendering and platform"]
  node_html["HTML rendering<br/>[html.go]"]
  node_markdown["Markdown conversion<br/>[markdown.go]"]
  node_pgp["Encryption<br/>[file.go]"]
  node_menubar["macOS menu helper"]
end

node_user(("Email user"))

node_user -->|"invokes"| node_cli
node_cli -->|"launches"| node_application
node_application -.->|"presents"| node_inbox
node_application -->|"requests mail"| node_fetcher
node_application -->|"coordinates actions"| node_actions
node_search -.->|"requests search"| node_fetcher
node_application -.->|"opens message"| node_emailview
node_actions -->|"executes mailbox action"| node_service
node_service -.->|"routes RPC"| node_daemon
node_daemon -->|"calls provider"| node_protocol
node_service -->|"direct fallback"| node_protocol
node_protocol -.->|"implemented by"| node_jmap
node_protocol -.->|"implemented by"| node_maildir
node_protocol -.->|"implemented by"| node_pop3
node_application -.->|"sends mail"| node_sender
node_application -.->|"exports mail"| node_export
node_application -->|"integrates plugins"| node_pluginbridge
node_pluginbridge -->|"dispatches hooks"| node_plugins
node_plugins -->|"persists plugin data"| node_pluginstore
node_marketplace -.->|"supplies plugins"| node_plugins
node_emailview -->|"renders HTML"| node_html
node_sender -->|"uses encryption"| node_pgp
node_menubar -->|"shows mail status"| node_user
node_emailview -.->|"converts content"| node_markdown

click node_cli "https://github.com/floatpane/matcha/blob/master/main.go"
click node_application "https://github.com/floatpane/matcha/blob/master/app/app.go"
click node_inbox "https://github.com/floatpane/matcha/blob/master/tui/inbox.go"
click node_search "https://github.com/floatpane/matcha/blob/master/tui/search.go"
click node_emailview "https://github.com/floatpane/matcha/blob/master/tui/email_view.go"
click node_actions "https://github.com/floatpane/matcha/blob/master/internal/emailactions/manager.go"
click node_fetcher "https://github.com/floatpane/matcha/blob/master/fetcher/fetcher.go"
click node_service "https://github.com/floatpane/matcha/blob/master/daemonclient/service.go"
click node_daemon "https://github.com/floatpane/matcha/blob/master/daemon/handler.go"
click node_protocol "https://github.com/floatpane/matcha/blob/master/backend/backend.go"
click node_jmap "https://github.com/floatpane/matcha/blob/master/backend/jmap/jmap.go"
click node_maildir "https://github.com/floatpane/matcha/blob/master/backend/maildir/maildir.go"
click node_pop3 "https://github.com/floatpane/matcha/blob/master/backend/pop3/pop3.go"
click node_sender "https://github.com/floatpane/matcha/blob/master/sender/sender.go"
click node_export "https://github.com/floatpane/matcha/blob/master/export/export.go"
click node_plugins "https://github.com/floatpane/matcha/blob/master/plugin/plugin.go"
click node_pluginbridge "https://github.com/floatpane/matcha/blob/master/internal/pluginbridge/manager.go"
click node_marketplace "https://github.com/floatpane/matcha/blob/master/internal/marketplace/client.go"
click node_pluginstore "https://github.com/floatpane/matcha/blob/master/plugin/storage.go"
click node_html "https://github.com/floatpane/matcha/blob/master/view/html.go"
click node_markdown "https://github.com/floatpane/matcha/blob/master/clib/markdown.go"
click node_pgp "https://github.com/floatpane/matcha/blob/master/pgp/file.go"
click node_menubar "https://github.com/floatpane/matcha/blob/master/cli/macos_menubar.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_cli,node_application,node_inbox,node_search,node_emailview,node_user toneBlue
class node_actions,node_fetcher,node_service,node_daemon,node_protocol,node_jmap,node_maildir,node_pop3,node_sender,node_export toneAmber
class node_plugins,node_pluginbridge,node_marketplace,node_pluginstore toneMint
class node_html,node_markdown,node_pgp,node_menubar toneRose
```

## Components

### Terminal client

- [CLI entry](https://github.com/floatpane/matcha/blob/master/main.go): `main.go`
- [Application model](https://github.com/floatpane/matcha/blob/master/app/app.go): `app/app.go`
- [Inbox and views](https://github.com/floatpane/matcha/blob/master/tui/inbox.go): `tui/inbox.go`
- [Mail search](https://github.com/floatpane/matcha/blob/master/tui/search.go): `tui/search.go`
- [Message view](https://github.com/floatpane/matcha/blob/master/tui/email_view.go): `tui/email_view.go`

### Mail operations

- [Message actions](https://github.com/floatpane/matcha/blob/master/internal/emailactions/manager.go): `internal/emailactions/manager.go`
- [Fetch and search](https://github.com/floatpane/matcha/blob/master/fetcher/fetcher.go): `fetcher/fetcher.go`
- [Mailbox service](https://github.com/floatpane/matcha/blob/master/daemonclient/service.go): `daemonclient/service.go`
- [Mailbox daemon](https://github.com/floatpane/matcha/blob/master/daemon/handler.go): `daemon/handler.go`
- [Provider interface](https://github.com/floatpane/matcha/blob/master/backend/backend.go): `backend/backend.go`
- [JMAP provider](https://github.com/floatpane/matcha/blob/master/backend/jmap/jmap.go): `backend/jmap/jmap.go`
- [Maildir provider](https://github.com/floatpane/matcha/blob/master/backend/maildir/maildir.go): `backend/maildir/maildir.go`
- [POP3 provider](https://github.com/floatpane/matcha/blob/master/backend/pop3/pop3.go): `backend/pop3/pop3.go`
- [Message sending](https://github.com/floatpane/matcha/blob/master/sender/sender.go): `sender/sender.go`
- [Mail export](https://github.com/floatpane/matcha/blob/master/export/export.go): `export/export.go`

### Plugins and extensions

- [Plugin runtime](https://github.com/floatpane/matcha/blob/master/plugin/plugin.go): `plugin/plugin.go`
- [TUI plugin bridge](https://github.com/floatpane/matcha/blob/master/internal/pluginbridge/manager.go): `internal/pluginbridge/manager.go`
- [Plugin marketplace](https://github.com/floatpane/matcha/blob/master/internal/marketplace/client.go): `internal/marketplace/client.go`
- [Plugin storage](https://github.com/floatpane/matcha/blob/master/plugin/storage.go): `plugin/storage.go`

### Rendering and platform

- [HTML rendering](https://github.com/floatpane/matcha/blob/master/view/html.go): `view/html.go`
- [Markdown conversion](https://github.com/floatpane/matcha/blob/master/clib/markdown.go): `clib/markdown.go`
- [Encryption](https://github.com/floatpane/matcha/blob/master/pgp/file.go): `pgp/file.go`
- [macOS menu helper](https://github.com/floatpane/matcha/blob/master/cli/macos_menubar.swift): `cli/macos_menubar.swift`

### Other components

- **Email user**

## Connections

- Email user → CLI entry: invokes (evidence: `README.md`)
- CLI entry → Application model: launches (evidence: `main.go`)
- Application model → Inbox and views: presents
- Application model → Fetch and search: requests mail (evidence: `app/app.go`)
- Application model → Message actions: coordinates actions (evidence: `app/app.go`)
- Mail search → Fetch and search: requests search
- Application model → Message view: opens message
- Message actions → Mailbox service: executes mailbox action (evidence: `internal/emailactions/manager.go`)
- Mailbox service → Mailbox daemon: routes RPC
- Mailbox daemon → Provider interface: calls provider (evidence: `daemon/handler.go`)
- Mailbox service → Provider interface: direct fallback (evidence: `daemonclient/service.go`)
- Provider interface → JMAP provider: implemented by
- Provider interface → Maildir provider: implemented by
- Provider interface → POP3 provider: implemented by
- Application model → Message sending: sends mail
- Application model → Mail export: exports mail
- Application model → TUI plugin bridge: integrates plugins (evidence: `app/app.go`)
- TUI plugin bridge → Plugin runtime: dispatches hooks (evidence: `internal/pluginbridge/manager.go`)
- Plugin runtime → Plugin storage: persists plugin data (evidence: `plugin/storage.go`)
- Plugin marketplace → Plugin runtime: supplies plugins (evidence: `README.md`)
- Message view → HTML rendering: renders HTML (evidence: `view/html.go`)
- Message sending → Encryption: uses encryption (evidence: `sender/sender.go`)
- macOS menu helper → Email user: shows mail status (evidence: `README.md`)
- Message view → Markdown conversion: converts content
