# arminsalmasi/intelligent-email-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/arminsalmasi/intelligent-email-assistant
- Repository: https://github.com/arminsalmasi/intelligent-email-assistant

## Overview

Email Assistant is a human-approved email workflow: it loads and guards inbox threads, classifies and ranks them, then runs per-thread workers to summarize, draft, schedule, or propose follow-ups. The graph applies deterministic policy checks and pauses outgoing actions for human review before execution. The service composes the runtime, including LLM, memory, tools, and telemetry. README documents the main flow and worker routing; some wiring is inferred only from the SOURCE INDEX, so uncertain relationships are omitted.

Main entry points: [`email_assistant/graph/thread_graph.py`](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/thread_graph.py) (Thread graph), [`email_assistant/service.py`](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/service.py) (Service composition), [`email_assistant/graph/orchestrator.py`](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/orchestrator.py) (Inbox orchestration), [`email_assistant/safety/policy.py`](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/safety/policy.py) (Action policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["API<br/>[main.py]"]
  node_dashboard["Dashboard<br/>[app.py]"]
end

subgraph group_workflow["Inbox workflow"]
  node_inbox["Inbox orchestration<br/>[orchestrator.py]"]
  node_guard["Threat guard<br/>[injection.py]"]
  node_triage["Triage and ranking<br/>[triage.py]"]
  node_thread["Thread graph<br/>[thread_graph.py]"]
end

subgraph group_workers["Thread workers"]
  node_summarizer["Thread summaries<br/>[summarizer.py]"]
  node_drafter["Reply drafting<br/>[drafter.py]"]
  node_scheduler["Meeting scheduling<br/>[scheduler.py]"]
  node_followup["Follow-up proposals<br/>[followup.py]"]
end

subgraph group_actions["Approval and actions"]
  node_policy["Action policy<br/>[policy.py]"]
  node_review["Human review<br/>[review.py]"]
  node_executor["Action execution<br/>[thread_graph.py]"]
end

subgraph group_runtime["Runtime services"]
  node_service["Service composition<br/>[service.py]"]
  node_mail["Mail provider<br/>[mail.py]"]
  node_tools["Mail, calendar, reminders"]
  node_memory[("Long-term memory<br/>[store.py]")]
  node_checkpoint[("Thread checkpoints<br/>[checkpointer.py]")]
  node_llm["LLM gateway and cache<br/>[client.py]"]
  node_schemas["Domain contracts"]
  node_telemetry[("Telemetry<br/>[metrics.py]")]
end

node_owner(("Mailbox owner"))

node_owner -->|"uses"| node_cli
node_owner -->|"uses"| node_api
node_owner -->|"reviews in"| node_dashboard
node_cli -->|"builds"| node_service
node_api -->|"builds"| node_service
node_dashboard -.->|"uses"| node_api
node_service -->|"constructs"| node_inbox
node_inbox -->|"fetches threads"| node_mail
node_inbox -->|"scans threads"| node_guard
node_inbox -->|"triages and ranks"| node_triage
node_inbox -->|"runs per thread"| node_thread
node_thread -->|"routes to"| node_summarizer
node_thread -->|"routes to"| node_drafter
node_thread -->|"routes to"| node_scheduler
node_thread -->|"routes to"| node_followup
node_thread -->|"checks proposals"| node_policy
node_policy -->|"requests approval"| node_review
node_review -->|"resumes graph"| node_thread
node_thread -->|"dispatches approved"| node_executor
node_executor -->|"executes actions"| node_tools
node_drafter -->|"retrieves context"| node_memory
node_policy -->|"checks protected facts"| node_memory
node_policy -->|"validates calendar"| node_tools
node_thread -->|"checkpoints runs"| node_checkpoint
node_service -->|"configures"| node_llm
node_service -->|"builds"| node_memory
node_service -->|"builds"| node_tools
node_service -->|"initializes"| node_telemetry
node_llm -->|"records calls"| node_telemetry
node_triage -->|"uses contracts"| node_schemas
node_thread -->|"uses contracts"| node_schemas

click node_cli "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/cli.py"
click node_api "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/api/main.py"
click node_dashboard "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/dashboard/app.py"
click node_service "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/service.py"
click node_inbox "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/orchestrator.py"
click node_mail "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/tools/mail.py"
click node_guard "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/safety/injection.py"
click node_triage "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/triage.py"
click node_thread "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/thread_graph.py"
click node_summarizer "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/summarizer.py"
click node_drafter "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/drafter.py"
click node_scheduler "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/scheduler.py"
click node_followup "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/followup.py"
click node_policy "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/safety/policy.py"
click node_review "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/schemas/review.py"
click node_executor "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/thread_graph.py"
click node_tools "https://github.com/arminsalmasi/intelligent-email-assistant/tree/main/email_assistant/tools"
click node_memory "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/memory/store.py"
click node_checkpoint "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/memory/checkpointer.py"
click node_llm "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/llm/client.py"
click node_schemas "https://github.com/arminsalmasi/intelligent-email-assistant/tree/main/email_assistant/schemas"
click node_telemetry "https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/observability/metrics.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_api,node_dashboard toneBlue
class node_inbox,node_guard,node_triage,node_thread toneAmber
class node_summarizer,node_drafter,node_scheduler,node_followup toneMint
class node_policy,node_review,node_executor toneRose
class node_service,node_mail,node_tools,node_memory,node_checkpoint,node_llm,node_schemas,node_telemetry,node_owner toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/cli.py): `email_assistant/cli.py`
- [API](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/api/main.py): `email_assistant/api/main.py`
- [Dashboard](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/dashboard/app.py): `dashboard/app.py`

### Inbox workflow

- [Inbox orchestration](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/orchestrator.py): `email_assistant/graph/orchestrator.py`
- [Threat guard](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/safety/injection.py): `email_assistant/safety/injection.py`
- [Triage and ranking](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/triage.py): `email_assistant/agents/triage.py`
- [Thread graph](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/thread_graph.py): `email_assistant/graph/thread_graph.py`

### Thread workers

- [Thread summaries](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/summarizer.py): `email_assistant/agents/summarizer.py`
- [Reply drafting](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/drafter.py): `email_assistant/agents/drafter.py`
- [Meeting scheduling](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/scheduler.py): `email_assistant/agents/scheduler.py`
- [Follow-up proposals](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/agents/followup.py): `email_assistant/agents/followup.py`

### Approval and actions

- [Action policy](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/safety/policy.py): `email_assistant/safety/policy.py`
- [Human review](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/schemas/review.py): `email_assistant/schemas/review.py`
- [Action execution](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/graph/thread_graph.py): `email_assistant/graph/thread_graph.py`

### Runtime services

- [Service composition](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/service.py): `email_assistant/service.py`
- [Mail provider](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/tools/mail.py): `email_assistant/tools/mail.py`
- [Mail, calendar, reminders](https://github.com/arminsalmasi/intelligent-email-assistant/tree/main/email_assistant/tools): `email_assistant/tools`
- [Long-term memory](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/memory/store.py): `email_assistant/memory/store.py`
- [Thread checkpoints](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/memory/checkpointer.py): `email_assistant/memory/checkpointer.py`
- [LLM gateway and cache](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/llm/client.py): `email_assistant/llm/client.py`
- [Domain contracts](https://github.com/arminsalmasi/intelligent-email-assistant/tree/main/email_assistant/schemas): `email_assistant/schemas`
- [Telemetry](https://github.com/arminsalmasi/intelligent-email-assistant/blob/main/email_assistant/observability/metrics.py): `email_assistant/observability/metrics.py`

### Other components

- **Mailbox owner**

## Connections

- Mailbox owner → CLI: uses (evidence: `README.md`)
- Mailbox owner → API: uses (evidence: `README.md`)
- Mailbox owner → Dashboard: reviews in (evidence: `README.md`)
- CLI → Service composition: builds (evidence: `email_assistant/cli.py`)
- API → Service composition: builds (evidence: `email_assistant/api/main.py`)
- Dashboard → API: uses (evidence: `README.md`)
- Service composition → Inbox orchestration: constructs (evidence: `email_assistant/service.py`)
- Inbox orchestration → Mail provider: fetches threads (evidence: `README.md`)
- Inbox orchestration → Threat guard: scans threads (evidence: `README.md`)
- Inbox orchestration → Triage and ranking: triages and ranks (evidence: `README.md`)
- Inbox orchestration → Thread graph: runs per thread (evidence: `README.md`)
- Thread graph → Thread summaries: routes to (evidence: `README.md`)
- Thread graph → Reply drafting: routes to (evidence: `README.md`)
- Thread graph → Meeting scheduling: routes to (evidence: `README.md`)
- Thread graph → Follow-up proposals: routes to (evidence: `README.md`)
- Thread graph → Action policy: checks proposals (evidence: `README.md`)
- Action policy → Human review: requests approval (evidence: `README.md`)
- Human review → Thread graph: resumes graph (evidence: `README.md`)
- Thread graph → Action execution: dispatches approved (evidence: `README.md`)
- Action execution → Mail, calendar, reminders: executes actions (evidence: `README.md`)
- Reply drafting → Long-term memory: retrieves context (evidence: `README.md`)
- Action policy → Long-term memory: checks protected facts (evidence: `email_assistant/safety/policy.py`)
- Action policy → Mail, calendar, reminders: validates calendar (evidence: `email_assistant/safety/policy.py`)
- Thread graph → Thread checkpoints: checkpoints runs (evidence: `README.md`)
- Service composition → LLM gateway and cache: configures (evidence: `email_assistant/service.py`)
- Service composition → Long-term memory: builds (evidence: `email_assistant/service.py`)
- Service composition → Mail, calendar, reminders: builds (evidence: `email_assistant/service.py`)
- Service composition → Telemetry: initializes (evidence: `email_assistant/service.py`)
- LLM gateway and cache → Telemetry: records calls (evidence: `email_assistant/llm/client.py`)
- Triage and ranking → Domain contracts: uses contracts (evidence: `email_assistant/agents/triage.py`)
- Thread graph → Domain contracts: uses contracts (evidence: `email_assistant/graph/thread_graph.py`)
