# rirzoo/homer architecture

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

- Interactive diagram: https://gitdiagram.com/rirzoo/homer
- Repository: https://github.com/rirzoo/homer

## Overview

Homer gives people and AI agents a plain-text CLI for managing mail, plus a keyboard-driven TUI for hands-on reading and composition. The CLI selects an account backend; Gmail/IMAP and Outlook handle provider operations, while shared code builds and parses messages. The TUI adds conversation, folder, and compose workflows backed by local cache/state, and an optional daemon keeps that cache fresh and serves CLI requests. The README documents search, attachments, drafts, rules, and OpenPGP; excerpts do not expose every implementation path, so uncertain links are omitted.

Main entry points: [`homer/tui/mainscreen.py`](https://github.com/rirzoo/homer/blob/main/homer/tui/mainscreen.py) (Conversation screen), [`homer/cli.py`](https://github.com/rirzoo/homer/blob/main/homer/cli.py) (Mail CLI), [`homer/common.py`](https://github.com/rirzoo/homer/blob/main/homer/common.py) (Message utilities), [`homer/tui/app.py`](https://github.com/rirzoo/homer/blob/main/homer/tui/app.py) (TUI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["Mail CLI<br/>[cli.py]"]
  node_tui_app["TUI app<br/>[app.py]"]
end

subgraph group_mail["Mail operations"]
  node_gmail["Gmail / IMAP<br/>[gmail.py]"]
  node_outlook["Microsoft 365<br/>[outlook.py]"]
  node_common["Message utilities<br/>[common.py]"]
end

subgraph group_state["State and sync"]
  node_daemon["Background daemon<br/>[daemon.py]"]
  node_store[("Cache and account state<br/>[store.py]")]
end

subgraph group_tui["TUI experience"]
  node_main["Conversation screen<br/>[mainscreen.py]"]
  node_compose["Compose workflow<br/>[compose.py]"]
  node_reader["Message reader<br/>[reader.py]"]
  node_folders["Folder navigation<br/>[folders.py]"]
  node_modals["Pickers and dialogs<br/>[modals.py]"]
  node_widgets["Shared widgets<br/>[widgets.py]"]
  node_base["TUI helpers<br/>[base.py]"]
  node_look["Appearance controls<br/>[look.py]"]
  node_themes["Theme definitions<br/>[themes.py]"]
  node_kitty["Kitty integration<br/>[kitty.py]"]
end

node_person(("Person or agent"))
node_mail_service(("Mail providers"))
node_keyring[("System keyring")]
node_disk[("Local state files")]

node_person -->|"runs commands"| node_cli
node_person -->|"opens interface"| node_tui_app
node_cli -->|"dispatches mail"| node_gmail
node_cli -->|"dispatches mail"| node_outlook
node_cli -->|"builds messages"| node_common
node_cli -->|"requests service"| node_daemon
node_gmail -->|"uses utilities"| node_common
node_outlook -->|"uses utilities"| node_common
node_gmail -->|"connects to"| node_mail_service
node_outlook -->|"uses Graph"| node_mail_service
node_cli -.->|"stores credentials"| node_keyring
node_tui_app -->|"loads state"| node_store
node_tui_app -->|"starts screen"| node_main
node_tui_app -->|"loads appearance"| node_look
node_tui_app -->|"registers themes"| node_themes
node_tui_app -->|"checks window"| node_kitty
node_main -->|"reads and updates"| node_store
node_main -->|"uses background sync"| node_daemon
node_main -->|"opens composer"| node_compose
node_main -->|"opens conversation"| node_reader
node_main -->|"opens folder pane"| node_folders
node_main -->|"opens dialogs"| node_modals
node_main -->|"uses message helpers"| node_common
node_compose -->|"builds mail"| node_common
node_compose -->|"opens pickers"| node_modals
node_compose -->|"renders controls"| node_widgets
node_reader -->|"parses mail"| node_common
node_reader -->|"opens link picker"| node_modals
node_reader -->|"renders conversation"| node_widgets
node_folders -->|"uses folder pane"| node_widgets
node_look -->|"configures terminal"| node_kitty
node_look -->|"loads appearance state"| node_store
node_base -->|"formats mail state"| node_store
node_base -->|"parses messages"| node_common
node_daemon -->|"runs commands"| node_cli
node_daemon -->|"syncs cache"| node_store
node_daemon -->|"uses shared helpers"| node_common
node_store -.->|"reads and writes"| node_disk

click node_cli "https://github.com/rirzoo/homer/blob/main/homer/cli.py"
click node_tui_app "https://github.com/rirzoo/homer/blob/main/homer/tui/app.py"
click node_daemon "https://github.com/rirzoo/homer/blob/main/homer/daemon.py"
click node_gmail "https://github.com/rirzoo/homer/blob/main/homer/gmail.py"
click node_outlook "https://github.com/rirzoo/homer/blob/main/homer/outlook.py"
click node_common "https://github.com/rirzoo/homer/blob/main/homer/common.py"
click node_main "https://github.com/rirzoo/homer/blob/main/homer/tui/mainscreen.py"
click node_compose "https://github.com/rirzoo/homer/blob/main/homer/tui/compose.py"
click node_reader "https://github.com/rirzoo/homer/blob/main/homer/tui/reader.py"
click node_folders "https://github.com/rirzoo/homer/blob/main/homer/tui/folders.py"
click node_modals "https://github.com/rirzoo/homer/blob/main/homer/tui/modals.py"
click node_widgets "https://github.com/rirzoo/homer/blob/main/homer/tui/widgets.py"
click node_base "https://github.com/rirzoo/homer/blob/main/homer/tui/base.py"
click node_look "https://github.com/rirzoo/homer/blob/main/homer/tui/look.py"
click node_themes "https://github.com/rirzoo/homer/blob/main/homer/tui/themes.py"
click node_kitty "https://github.com/rirzoo/homer/blob/main/homer/tui/kitty.py"
click node_store "https://github.com/rirzoo/homer/blob/main/homer/store.py"

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_tui_app toneBlue
class node_gmail,node_outlook,node_common,node_keyring,node_disk toneAmber
class node_daemon,node_store toneMint
class node_main,node_compose,node_reader,node_folders,node_modals,node_widgets,node_base,node_look,node_themes,node_kitty toneRose
class node_person,node_mail_service toneIndigo
```

## Components

### User interfaces

- [Mail CLI](https://github.com/rirzoo/homer/blob/main/homer/cli.py): `homer/cli.py`
- [TUI app](https://github.com/rirzoo/homer/blob/main/homer/tui/app.py): `homer/tui/app.py`

### Mail operations

- [Gmail / IMAP](https://github.com/rirzoo/homer/blob/main/homer/gmail.py): `homer/gmail.py`
- [Microsoft 365](https://github.com/rirzoo/homer/blob/main/homer/outlook.py): `homer/outlook.py`
- [Message utilities](https://github.com/rirzoo/homer/blob/main/homer/common.py): `homer/common.py`

### State and sync

- [Background daemon](https://github.com/rirzoo/homer/blob/main/homer/daemon.py): `homer/daemon.py`
- [Cache and account state](https://github.com/rirzoo/homer/blob/main/homer/store.py): `homer/store.py`

### TUI experience

- [Conversation screen](https://github.com/rirzoo/homer/blob/main/homer/tui/mainscreen.py): `homer/tui/mainscreen.py`
- [Compose workflow](https://github.com/rirzoo/homer/blob/main/homer/tui/compose.py): `homer/tui/compose.py`
- [Message reader](https://github.com/rirzoo/homer/blob/main/homer/tui/reader.py): `homer/tui/reader.py`
- [Folder navigation](https://github.com/rirzoo/homer/blob/main/homer/tui/folders.py): `homer/tui/folders.py`
- [Pickers and dialogs](https://github.com/rirzoo/homer/blob/main/homer/tui/modals.py): `homer/tui/modals.py`
- [Shared widgets](https://github.com/rirzoo/homer/blob/main/homer/tui/widgets.py): `homer/tui/widgets.py`
- [TUI helpers](https://github.com/rirzoo/homer/blob/main/homer/tui/base.py): `homer/tui/base.py`
- [Appearance controls](https://github.com/rirzoo/homer/blob/main/homer/tui/look.py): `homer/tui/look.py`
- [Theme definitions](https://github.com/rirzoo/homer/blob/main/homer/tui/themes.py): `homer/tui/themes.py`
- [Kitty integration](https://github.com/rirzoo/homer/blob/main/homer/tui/kitty.py): `homer/tui/kitty.py`

### Other components

- **Person or agent**
- **Mail providers**
- **System keyring**
- **Local state files**

## Connections

- Person or agent → Mail CLI: runs commands (evidence: `README.md`)
- Person or agent → TUI app: opens interface (evidence: `README.md`)
- Mail CLI → Gmail / IMAP: dispatches mail (evidence: `homer/cli.py`)
- Mail CLI → Microsoft 365: dispatches mail (evidence: `homer/cli.py`)
- Mail CLI → Message utilities: builds messages (evidence: `homer/cli.py`)
- Mail CLI → Background daemon: requests service (evidence: `homer/cli.py`)
- Gmail / IMAP → Message utilities: uses utilities (evidence: `homer/gmail.py`)
- Microsoft 365 → Message utilities: uses utilities (evidence: `homer/outlook.py`)
- Gmail / IMAP → Mail providers: connects to (evidence: `README.md`)
- Microsoft 365 → Mail providers: uses Graph (evidence: `README.md`)
- Mail CLI → System keyring: stores credentials
- TUI app → Cache and account state: loads state (evidence: `homer/tui/app.py`)
- TUI app → Conversation screen: starts screen (evidence: `homer/tui/app.py`)
- TUI app → Appearance controls: loads appearance (evidence: `homer/tui/app.py`)
- TUI app → Theme definitions: registers themes (evidence: `homer/tui/app.py`)
- TUI app → Kitty integration: checks window (evidence: `homer/tui/app.py`)
- Conversation screen → Cache and account state: reads and updates (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Background daemon: uses background sync (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Compose workflow: opens composer (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Message reader: opens conversation (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Folder navigation: opens folder pane (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Pickers and dialogs: opens dialogs (evidence: `homer/tui/mainscreen.py`)
- Conversation screen → Message utilities: uses message helpers (evidence: `homer/tui/mainscreen.py`)
- Compose workflow → Message utilities: builds mail (evidence: `homer/tui/compose.py`)
- Compose workflow → Pickers and dialogs: opens pickers (evidence: `homer/tui/compose.py`)
- Compose workflow → Shared widgets: renders controls (evidence: `homer/tui/compose.py`)
- Message reader → Message utilities: parses mail (evidence: `homer/tui/reader.py`)
- Message reader → Pickers and dialogs: opens link picker (evidence: `homer/tui/reader.py`)
- Message reader → Shared widgets: renders conversation (evidence: `homer/tui/reader.py`)
- Folder navigation → Shared widgets: uses folder pane (evidence: `homer/tui/folders.py`)
- Appearance controls → Kitty integration: configures terminal (evidence: `homer/tui/look.py`)
- Appearance controls → Cache and account state: loads appearance state (evidence: `homer/tui/look.py`)
- TUI helpers → Cache and account state: formats mail state (evidence: `homer/tui/base.py`)
- TUI helpers → Message utilities: parses messages (evidence: `homer/tui/base.py`)
- Background daemon → Mail CLI: runs commands (evidence: `homer/daemon.py`)
- Background daemon → Cache and account state: syncs cache (evidence: `homer/daemon.py`)
- Background daemon → Message utilities: uses shared helpers (evidence: `homer/daemon.py`)
- Cache and account state → Local state files: reads and writes