# tonykipkemboi/crewai-gmail-automation architecture

> Architecture diagram of the GitHub repository tonykipkemboi/crewai-gmail-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/tonykipkemboi/crewai-gmail-automation
- Repository: https://github.com/tonykipkemboi/crewai-gmail-automation

## Overview

##### Project Type and Purpose
- This is an open-source Python CLI tool (not a web or mobile app) named “Gmail Automation with CrewAI.”
- Purpose: Automate Gmail inbox management—categorization, labeling, priority assignment, automated replies, cleanup—and send Slack notifications for high-priority emails, leveraging LLM agents via external APIs.

##### File Structure
- Top-level files and directories:
- `.env_example`, `pyproject.toml`: configuration and packaging
- `src/gmail_crew_ai/` – core Python package
- `src/gmail_crew_ai/config/` – YAML configurations for agents and tasks
- `src/gmail_crew_ai/crew.py` – orchestrator class
- `src/gmail_crew_ai/main.py` – CLI entry point
- `src/gmail_crew_ai/models.py` – data models (email metadata, tasks)
- `src/gmail_crew_ai/tools/` – helpers (‘gmail_tools.py’, ‘slack_tool.py’, ‘date_tools.py’)
- `assets/`, `knowledge/` – static assets & user preference data
- Key patterns:
- Modular design: orchestration, configuration, tooling, models separated by directory
- External integrations: IMAP server (Gmail), LLM provider (OpenAI/Gemini/Ollama), Slack Webhook

##### Extract Insights from the README
- Technical stack: Python 3, IMAP, SSL, LLM API calls, Slack incoming webhooks
- Workflow steps: fetch unread emails → categorize/assign priority → apply Gmail labels/stars → draft AI-generated replies → send Slack alerts → cleanup & trash management
- Configurable via `.env` (credentials) and `agents.yaml`/`tasks.yaml`

a. Main Components
1. CLI Launcher (main.py)
2. Orchestrator (Crew class in crew.py)
3. Configuration Store (agents.yaml, tasks.yaml, .env)
4. IMAP Client Module (gmail_tools.py)
5. LLM Agent Module (models.py + external API client)
6. Slack Notifier Module (slack_tool.py)
7. Date/Time Helpers (date_tools.py)
8. Knowledge Base (knowledge/user_preference.txt)
9. External Services:
- Gmail IMAP Server
- OpenAI/Gemini/Ollama API
- Slack Incoming Webhook

b. Relationships and Data Flow
- User runs `crewai run` → CLI Launcher
- CLI passes input (num of emails) to Orchestrator
- Orchestrator reads `.env` and YAML configs
- Orchestrator calls IMAP Client to fetch unread emails
- Emails → Data Models → passed to LLM Agent for categorization and response generation
- LLM Agent calls external LLM API
- Categorized emails → IMAP Client applies labels, stars, moves/trashes messages
- For high-priority: Orchestrator → Slack Notifier → Slack Webhook
- Cleanup logic uses Date Helpers + Gmail tools
- Knowledge Base consulted for user preferences or persistent rules

c. Architectural Patterns and Principles
- Separation of Concerns: distinct modules for config, orchestration, tooling, models
- Dependency Injection: pass config and clients into the Crew orchestrator
- Extensibility: agents/tasks YAML files allow adding new behaviors without code changes
- Fail-safe cleanup: ensures IMAP connections close properly

d. Key Technologies
- Python 3, imaplib (or a similar IMAP wrapper)
- YAML for configuration
- OpenAI/Gemini/Ollama LLM API
- Slack Incoming Webhooks
- `.env` for secrets management

##### Detail
- Even small helpers (date_tools) as they play a role in cleanup rules.
- Lifecycle of a single email and how it traverses through modules.
- Configuration flow: .env → environment variables → modules reading credentials, and YAML → modules loading behavior rules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Internal Modules
    subgraph "Internal Modules"
        CLI["CLI Launcher"]:::internal
        CREW["Orchestrator (Crew)"]:::internal
        IMAP["IMAP Client Module"]:::internal
        MODELS["LLM Agent Module"]:::internal
        SLACKTOOL["Slack Notifier Module"]:::internal
        DATE["Date/Time Helpers"]:::internal
    end

    %% Config & Data Sources
    subgraph "Configuration & Data"
        ENV[".env (example)"]:::config
        AGENTS["agents.yaml"]:::config
        TASKS["tasks.yaml"]:::config
        KB["user_preference.txt"]:::config
        ASSETS["assets/"]:::config
    end

    %% External Services
    subgraph "External Services"
        GMAIL["Gmail IMAP Server"]:::external
        LLM["LLM Provider API"]:::external
        SLACK["Slack Incoming Webhook"]:::external
    end

    %% Connections
    CLI -->|"run crewai"| CREW
    CREW -->|"load .env"| ENV
    CREW -->|"load agents.yaml"| AGENTS
    CREW -->|"load tasks.yaml"| TASKS
    CREW -->|"consult preferences"| KB
    CREW -->|"fetch unread emails"| IMAP
    IMAP -->|"IMAP Fetch"| GMAIL
    GMAIL -->|"emails"| IMAP
    IMAP -->|"Email Objects"| MODELS
    MODELS -->|"API Call"| LLM
    LLM -->|"Responses"| MODELS
    MODELS -->|"categorized emails"| CREW
    CREW -->|"apply labels & cleanup"| IMAP
    IMAP -->|"label/move/trash"| GMAIL
    CREW -->|"apply cleanup rules"| DATE
    CREW -->|"high-priority alerts"| SLACKTOOL
    SLACKTOOL -->|"send webhook"| SLACK

    %% Click Events
    click CLI "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/main.py"
    click CREW "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/crew.py"
    click ENV "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/.env_example"
    click AGENTS "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/config/agents.yaml"
    click TASKS "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/config/tasks.yaml"
    click KB "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/knowledge/user_preference.txt"
    click ASSETS "https://github.com/tonykipkemboi/crewai-gmail-automation/tree/main/assets"
    click IMAP "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/tools/gmail_tools.py"
    click MODELS "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/models.py"
    click SLACKTOOL "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/tools/slack_tool.py"
    click DATE "https://github.com/tonykipkemboi/crewai-gmail-automation/blob/main/src/gmail_crew_ai/tools/date_tools.py"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#000;
    classDef config fill:#E6FFEA,stroke:#28a745,color:#000;
    classDef external fill:#FFF5E6,stroke:#d93f0b,color:#000;
```
