# kaymen99/langgraph-email-automation architecture

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

- Interactive diagram: https://gitdiagram.com/kaymen99/langgraph-email-automation
- Repository: https://github.com/kaymen99/langgraph-email-automation

## Overview

##### Project type and purpose
- This is a Python-based AI automation system (no UI frontend) that implements a Langgraph workflow of AI agents to monitor a Gmail inbox, categorize incoming emails, retrieve relevant data via RAG, draft and verify responses, and send them back—all orchestrated as a script (main.py) or a deployable API (deploy_api.py).

##### File structure
- Top-level scripts:
- main.py – runs the end-to-end workflow
- deploy_api.py – serves the same workflow over FastAPI (Langserve)
- create_index.py – builds a Chroma vector store from files in data/
- Data & Storage:
- data/agency.txt – raw documents for RAG
- db/… – Chroma’s binary index files + chroma.sqlite3 for persistence
- Source code in src/:
- src/graph.py – constructs the Langgraph graph of interconnected nodes (agents)
- src/agents.py, nodes.py, prompts.py, state.py, structure_outputs.py – implement each AI agent’s logic, prompts, state management, and output formatting
- src/tools/GmailTools.py – a wrapper around the Gmail API for fetching/sending mails
- Config & dependencies:
- requirements.txt, .env variables for Gmail credentials, GROQ_API_KEY, GOOGLE_API_KEY

##### README for additional insights
- Workflow steps: monitor inbox → categorize → RAG retrieval for product answers → draft replies → quality-check → send
- Tech stack: Langchain/Langgraph for orchestration, Groq & Gemini LLM APIs, Gmail API, FastAPI for API endpoints

##### Detail
- Create_index.py indexing step feeding into the Vector Store.
- Environment/config (API keys) as a sidebar or annotation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GmailInbox("Gmail Inbox"):::external
    GroqAPI("Groq LLM API"):::external
    GeminiAPI("Google Gemini API"):::external

    %% Tools Layer
    GmailTools["GmailTools<br/>(Python Gmail API wrapper)"]:::tools
    click GmailTools "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/tools/GmailTools.py"

    %% Orchestrator Layer
    subgraph "Orchestrator"
        direction TB
        GraphDef["Langgraph Graph Definition"]:::orchestrator
        click GraphDef "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/graph.py"
        MainScript["main.py<br/>(CLI Workflow)"]:::orchestrator
        click MainScript "https://github.com/kaymen99/langgraph-email-automation/blob/main/main.py"
        DeployAPI["deploy_api.py<br/>(FastAPI Service)"]:::api
        click DeployAPI "https://github.com/kaymen99/langgraph-email-automation/blob/main/deploy_api.py"
    end

    %% API Layer
    APILayer["FastAPI Endpoints"]:::api
    click APILayer "https://github.com/kaymen99/langgraph-email-automation/blob/main/deploy_api.py"

    %% Agents Pipeline
    subgraph "AI Agent Nodes"
        direction TB
        EmailMonitor["Email Monitor Node"]:::agent
        click EmailMonitor "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/nodes.py"
        Categorization["Categorization Node"]:::agent
        click Categorization "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/nodes.py"
        Retrieval["Retrieval (RAG) Node"]:::agent
        click Retrieval "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/agents.py"
        DraftGen["Draft-Generation Node"]:::agent
        click DraftGen "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/agents.py"
        QualityCheck["Quality-Check Node"]:::agent
        click QualityCheck "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/agents.py"
        SendEmail["Send-Email Node"]:::agent
        click SendEmail "https://github.com/kaymen99/langgraph-email-automation/blob/main/src/agents.py"
    end

    %% Data Stores
    RawData["Raw Data Store<br/>(agency.txt)"]:::storage
    click RawData "https://github.com/kaymen99/langgraph-email-automation/blob/main/data/agency.txt"
    VectorStore["Chroma Vector Store<br/>(db/)"]:::storage
    click VectorStore "https://github.com/kaymen99/langgraph-email-automation/tree/main/db/"

    %% Indexing Step
    CreateIndex["create_index.py<br/>(builds Chroma index)"]:::tools
    click CreateIndex "https://github.com/kaymen99/langgraph-email-automation/blob/main/create_index.py"

    %% Dependencies & Config
    Requirements["requirements.txt"]:::tools
    click Requirements "https://github.com/kaymen99/langgraph-email-automation/blob/main/requirements.txt"

    %% Connections
    GmailInbox --> GmailTools --> EmailMonitor --> Categorization
    Categorization -->|product question| Retrieval
    Retrieval --> VectorStore
    CreateIndex --> VectorStore
    Retrieval --> GroqAPI
    Retrieval --> GeminiAPI
    DraftGen --> GroqAPI
    DraftGen --> GeminiAPI
    QualityCheck --> GroqAPI
    QualityCheck --> GeminiAPI
    Categorization -->|non-product| DraftGen
    Retrieval --> DraftGen
    DraftGen --> QualityCheck --> SendEmail --> GmailTools --> GmailInbox

    %% Orchestrator integration
    GraphDef --> EmailMonitor
    GraphDef --> Categorization
    GraphDef --> Retrieval
    GraphDef --> DraftGen
    GraphDef --> QualityCheck
    GraphDef --> SendEmail
    MainScript --> GraphDef
    DeployAPI --> GraphDef
    DeployAPI --> APILayer
    APILayer --> MainScript

    %% Styles
    classDef external fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef tools fill:#F1F8E9,stroke:#33691E,stroke-width:2px;
    classDef orchestrator fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef agent fill:#EDE7F6,stroke:#512DA8,stroke-width:2px;
    classDef api fill:#F3E5F5,stroke:#4A148C,stroke-width:2px;
    classDef storage fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
```
