# parthshr370/email-ai-agent architecture

> Architecture diagram of the GitHub repository parthshr370/email-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/parthshr370/email-ai-agent
- Repository: https://github.com/parthshr370/email-ai-agent

## Overview

##### Project Type and Purpose
- This is a backend-only, AI-driven email automation pipeline written in Python.
- Purpose: fetch emails (live or simulated), classify and summarize them via LLMs, draft replies, allow human review, and send responses via SMTP.
- It leverages a state-graph workflow (LangGraph) to orchestrate agents at each processing step.

##### File Structure
- Top-level scripts:
- main.py: entry point
- email.sh: auxiliary shell script
- test_email.py: unit tests
- Configuration:
- config.py: loads environment variables (.env)
- Core modules (core/):
- email_imap.py: IMAP connector for live fetching
- email_ingestion.py: JSON-based simulation loader
- email_sender.py: SMTP integration
- state.py: EmailState data model
- supervisor.py: orchestrates the state graph workflow
- Agents (agents/):
- filtering_agent.py
- summarization_agent.py
- response_agent.py
- human_review_agent.py
- Utilities (utils/):
- formatter.py: email formatting helpers
- logger.py: centralized logging setup

##### Extract Architectural Insights from README
- Workflow steps: Ingestion → Filtering → Summarization → Response Generation → (Optional) Human Review → Sending/Drafting.
- Integrations: Deepseek API for LLM calls, IMAP server for fetching, SMTP server for sending.
- State Graph: conditional transitions based on classification results.

##### Main Components
a. Ingestion Layer
- IMAP Connector (core/email_imap)
- JSON Loader (core/email_ingestion)
b. Controller / Orchestrator
- State-Graph Supervisor (core/supervisor)
- EmailState Model (core/state)
c. Agent Layer
- Filtering Agent (classifies emails)
- Summarization Agent
- Response Agent (drafts replies)
- Human Review Agent (prompts for manual edits)
d. Delivery Layer
- SMTP Sender (core/email_sender)
- Draft Handler (writes drafts to file or Gmail)
e. External Services
- Deepseek API (LLM calls)
- IMAP Server
- SMTP Server

##### Relationships and Data Flow
- Conditional branch: If “needs review” → Human Review Agent → Supervisor
- External calls from each agent/component to Deepseek API.

##### Architectural Patterns and Design Principles
- Pipeline / Chain of Responsibility: each agent handles one responsibility.
- State Machine / Workflow: LangGraph manages step transitions.
- Modular Separation: core vs agents vs utils.
- Dependency Injection via config.py for credentials and API keys.
- Testability: clear boundaries enable unit tests (test_email.py).

##### Technologies and Frameworks
- Python 3.8+
- Deepseek API (LLM backend)
- LangGraph (state graph orchestrator)
- IMAP & SMTP protocols
- Logging with utils/logger.py
- Formatting utilities in utils/formatter.py

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Entry & Configuration"
        Launcher["main.py"]:::script
        Config["config.py"]:::config
        Script["email.sh"]:::script
        Test["test_email.py"]:::test
    end

    subgraph "Ingestion Layer"
        IMAP["IMAP Connector"]:::ingestion
        JSONLoader["JSON Loader"]:::ingestion
    end

    subgraph "Controller / Orchestrator"
        Supervisor["State-Graph Supervisor"]:::supervisor
        StateModel["EmailState Model"]:::supervisor
    end

    subgraph "Agent Layer"
        Filter["Filtering Agent"]:::agent
        Summarize["Summarization Agent"]:::agent
        Respond["Response Agent"]:::agent
        HumanReview["Human Review Agent"]:::agent
    end

    subgraph "Delivery Layer"
        SMTPSender["SMTP Sender"]:::delivery
        DraftHandler["Draft Handler"]:::delivery
    end

    subgraph "Utilities"
        Formatter["Formatting Helpers"]:::util
        Logger["Centralized Logging"]:::util
    end

    subgraph "External Services"
        IMAPServer["IMAP Server"]:::external
        SMTPServer["SMTP Server"]:::external
        Deepseek["Deepseek API"]:::external
    end

    %% Entry & Config flows
    Config -->|loads env| Launcher
    Launcher --> IMAP
    Launcher --> JSONLoader
    Script --> Launcher
    Test --> Launcher

    %% Ingestion to Supervisor
    IMAP -->|raw email| Supervisor
    JSONLoader -->|simulated email| Supervisor
    IMAP -->|connects to| IMAPServer

    %% Supervisor and StateModel
    Supervisor --> StateModel

    %% Supervisor to Agents
    Supervisor --> Filter
    Filter --> Supervisor
    Filter -->|calls LLM| Deepseek

    Supervisor --> Summarize
    Summarize --> Supervisor
    Summarize -->|calls LLM| Deepseek

    Supervisor --> Respond
    Respond --> Supervisor
    Respond -->|calls LLM| Deepseek

    Supervisor -->|needs_review?| HumanReview
    HumanReview --> Supervisor
    HumanReview -->|calls LLM| Deepseek

    %% Delivery
    Supervisor --> SMTPSender
    Supervisor --> DraftHandler
    SMTPSender -->|send email| SMTPServer

    %% Utilities usage
    Formatter --> Launcher
    Logger --> Launcher
    Logger --> Supervisor
    Logger --> Filter
    Logger --> Summarize
    Logger --> Respond
    Logger --> HumanReview
    Logger --> SMTPSender

    %% Click Events
    click IMAP "https://github.com/parthshr370/email-ai-agent/blob/main/core/email_imap.py"
    click JSONLoader "https://github.com/parthshr370/email-ai-agent/blob/main/core/email_ingestion.py"
    click Supervisor "https://github.com/parthshr370/email-ai-agent/blob/main/core/supervisor.py"
    click StateModel "https://github.com/parthshr370/email-ai-agent/blob/main/core/state.py"
    click Filter "https://github.com/parthshr370/email-ai-agent/blob/main/agents/filtering_agent.py"
    click Summarize "https://github.com/parthshr370/email-ai-agent/blob/main/agents/summarization_agent.py"
    click Respond "https://github.com/parthshr370/email-ai-agent/blob/main/agents/response_agent.py"
    click HumanReview "https://github.com/parthshr370/email-ai-agent/blob/main/agents/human_review_agent.py"
    click SMTPSender "https://github.com/parthshr370/email-ai-agent/blob/main/core/email_sender.py"
    click Config "https://github.com/parthshr370/email-ai-agent/blob/main/config.py"
    click Formatter "https://github.com/parthshr370/email-ai-agent/blob/main/utils/formatter.py"
    click Logger "https://github.com/parthshr370/email-ai-agent/blob/main/utils/logger.py"
    click Launcher "https://github.com/parthshr370/email-ai-agent/blob/main/main.py"
    click Test "https://github.com/parthshr370/email-ai-agent/blob/main/test_email.py"

    %% Styles
    classDef ingestion fill:#89CFF0,stroke:#333,stroke-width:1px
    classDef supervisor fill:#90EE90,stroke:#333,stroke-width:1px
    classDef agent fill:#FFA500,stroke:#333,stroke-width:1px
    classDef delivery fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef config fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef util fill:#f2f2f2,stroke:#333,stroke-width:1px
    classDef script fill:#efe1c6,stroke:#333,stroke-width:1px
    classDef test fill:#ececec,stroke:#333,stroke-width:1px
```
