# davideluzi/mail-agent architecture

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

- Interactive diagram: https://gitdiagram.com/davideluzi/mail-agent
- Repository: https://github.com/davideluzi/mail-agent

## Overview

Neuron AI is a terminal email assistant: a user submits a request through the CLI, the agent consults an AI provider and dispatches registered tools, and tool results are returned to the conversation. For sending, the agent searches contacts first; if no match exists, it asks the user for an address before sending. Separate tools support adding and listing contacts. Contact data is stored in SQLite, while composed emails are appended to a local log rather than actually delivered. The README documents the flow; sampled source confirms tool-to-model calls and provider configuration.

Main entry points: [`App/Agents/MailAgent.php`](https://github.com/davideluzi/mail-agent/blob/main/App/Agents/MailAgent.php) (Mail agent), [`App/Models/Contact.php`](https://github.com/davideluzi/mail-agent/blob/main/App/Models/Contact.php) (Contact repository), [`chat.php`](https://github.com/davideluzi/mail-agent/blob/main/chat.php) (Chat loop), [`App/Tools/SearchContactTool.php`](https://github.com/davideluzi/mail-agent/blob/main/App/Tools/SearchContactTool.php) (Search contact)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["CLI interaction"]
  node_cli["Chat loop<br/>[chat.php]"]
end

subgraph group_agent["Agent orchestration"]
  node_mail_agent["Mail agent<br/>[MailAgent.php]"]
  node_config["Configuration<br/>[Config.php]"]
end

subgraph group_contacts["Contact management"]
  node_search_tool["Search contact"]
  node_add_tool["Add contact<br/>[AddContactTool.php]"]
  node_list_tool["List contacts"]
  node_contact_model["Contact repository<br/>[Contact.php]"]
  node_contacts_db[("Contacts SQLite")]
end

subgraph group_mail["Email logging"]
  node_send_tool["Send mail tool<br/>[SendMailTool.php]"]
  node_email_model["Email builder<br/>[Email.php]"]
  node_mail_log["Sent-mail log"]
end

node_user(("Terminal user"))
node_ollama{{"Ollama"}}
node_anthropic{{"Anthropic"}}

node_user -->|"enters request"| node_cli
node_cli -->|"submits message"| node_mail_agent
node_mail_agent -->|"returns response"| node_cli
node_mail_agent -->|"reads settings"| node_config
node_mail_agent -->|"requests inference"| node_ollama
node_mail_agent -.->|"requests inference"| node_anthropic
node_mail_agent -->|"dispatches tool"| node_search_tool
node_mail_agent -->|"dispatches tool"| node_add_tool
node_mail_agent -->|"dispatches tool"| node_list_tool
node_mail_agent -->|"dispatches tool"| node_send_tool
node_search_tool -->|"searches contacts"| node_contact_model
node_add_tool -->|"adds contact"| node_contact_model
node_list_tool -->|"lists contacts"| node_contact_model
node_contact_model -->|"reads and writes"| node_contacts_db
node_send_tool -->|"builds email"| node_email_model
node_email_model -->|"appends message"| node_mail_log

click node_cli "https://github.com/davideluzi/mail-agent/blob/main/chat.php"
click node_mail_agent "https://github.com/davideluzi/mail-agent/blob/main/App/Agents/MailAgent.php"
click node_config "https://github.com/davideluzi/mail-agent/blob/main/App/Config.php"
click node_search_tool "https://github.com/davideluzi/mail-agent/blob/main/App/Tools/SearchContactTool.php"
click node_add_tool "https://github.com/davideluzi/mail-agent/blob/main/App/Tools/AddContactTool.php"
click node_list_tool "https://github.com/davideluzi/mail-agent/blob/main/App/Tools/ListContactsTool.php"
click node_contact_model "https://github.com/davideluzi/mail-agent/blob/main/App/Models/Contact.php"
click node_send_tool "https://github.com/davideluzi/mail-agent/blob/main/App/Tools/SendMailTool.php"
click node_email_model "https://github.com/davideluzi/mail-agent/blob/main/App/Models/Email.php"

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_user toneBlue
class node_mail_agent,node_config toneAmber
class node_search_tool,node_add_tool,node_list_tool,node_contact_model,node_contacts_db toneMint
class node_send_tool,node_email_model,node_mail_log toneRose
class node_ollama,node_anthropic toneIndigo
```

## Components

### CLI interaction

- [Chat loop](https://github.com/davideluzi/mail-agent/blob/main/chat.php): `chat.php`

### Agent orchestration

- [Mail agent](https://github.com/davideluzi/mail-agent/blob/main/App/Agents/MailAgent.php): `App/Agents/MailAgent.php`
- [Configuration](https://github.com/davideluzi/mail-agent/blob/main/App/Config.php): `App/Config.php`

### Contact management

- [Search contact](https://github.com/davideluzi/mail-agent/blob/main/App/Tools/SearchContactTool.php): `App/Tools/SearchContactTool.php`
- [Add contact](https://github.com/davideluzi/mail-agent/blob/main/App/Tools/AddContactTool.php): `App/Tools/AddContactTool.php`
- [List contacts](https://github.com/davideluzi/mail-agent/blob/main/App/Tools/ListContactsTool.php): `App/Tools/ListContactsTool.php`
- [Contact repository](https://github.com/davideluzi/mail-agent/blob/main/App/Models/Contact.php): `App/Models/Contact.php`
- **Contacts SQLite**

### Email logging

- [Send mail tool](https://github.com/davideluzi/mail-agent/blob/main/App/Tools/SendMailTool.php): `App/Tools/SendMailTool.php`
- [Email builder](https://github.com/davideluzi/mail-agent/blob/main/App/Models/Email.php): `App/Models/Email.php`
- **Sent-mail log**

### Other components

- **Terminal user**
- **Ollama**
- **Anthropic**

## Connections

- Terminal user → Chat loop: enters request
- Chat loop → Mail agent: submits message
- Mail agent → Chat loop: returns response
- Mail agent → Configuration: reads settings
- Mail agent → Ollama: requests inference
- Mail agent → Anthropic: requests inference
- Mail agent → Search contact: dispatches tool
- Mail agent → Add contact: dispatches tool
- Mail agent → List contacts: dispatches tool
- Mail agent → Send mail tool: dispatches tool
- Search contact → Contact repository: searches contacts
- Add contact → Contact repository: adds contact
- List contacts → Contact repository: lists contacts
- Contact repository → Contacts SQLite: reads and writes
- Send mail tool → Email builder: builds email
- Email builder → Sent-mail log: appends message