# wayswe/auto-gmail-responder architecture

> Architecture diagram of the GitHub repository wayswe/auto-gmail-responder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wayswe/auto-gmail-responder
- Repository: https://github.com/wayswe/auto-gmail-responder

## Overview

##### Project Type and Purpose
- This is a lightweight, local Windows-only automation tool written in Python (packaged as both a .py script and a standalone .exe).
- It watches a Gmail inbox, applies user-defined filters/prompts (from prompt_settings.csv), uses the OpenAI API to generate replies, sends those replies back through Gmail, and finally moves responded emails to a dedicated label.
- Per your “Please add SMS set up” instruction, we’ll also show how to integrate an SMS notification service (e.g., Twilio) so that, upon sending an email reply, the system can push an SMS alert to a user or administrator.

##### File Structure Analysis
- Top level:
- auto_gmail_responder.py (core script)
- auto_gmail_responder.exe (Windows build of the script)
- settings.env (configuration file for API keys, Gmail creds, run parameters)
- prompt_settings.csv (defines filters and ChatGPT prompts)
- README.md, LICENSE
- No “frontend/backend” split—this is a single process running locally.
- Uses environment variables (.env) for secrets.
- Relies on external REST APIs (Gmail, OpenAI, and now SMS).

##### Key Architecture Insights from README
- Single long-running service: polls Gmail at intervals set via settings.env.
- Filter engine: loads CSV rules, applies them to incoming messages.
- OpenAI integration: sends prompt + email content, receives AI-generated response.
- Gmail send + move: uses Gmail SMTP/IMAP or Gmail API to reply and relabel.
- Runs locally—no cloud deployment layer.

##### Main Components
a. Internal Components (deployed on the User’s Windows PC)
- Scheduler/Watcher Service (auto_gmail_responder.exe)
- Filter & Prompt Loader (reads prompt_settings.csv)
- OpenAI Client Module
- Gmail Client Module (IMAP/SMTP or Gmail API wrapper)
- SMS Notification Module (e.g., Twilio Python client)
- Configuration Store (settings.env)
b. External Services
- Gmail API Endpoint
- OpenAI API Endpoint
- SMS Provider API Endpoint (e.g., Twilio)
c. Optional Data Stores
- Local Log Files (for diagnostics)

##### Relationships and Data Flows
1. Scheduler triggers “CheckInbox” every N seconds.
2. Gmail Client polls Gmail API → retrieves new messages.
3. Filter Module evaluates each message against prompt_settings.csv.
4. For matching messages:
a. Prompt Builder injects email content into the user’s ChatGPT prompt.
b. OpenAI Client calls the OpenAI API → returns AI-generated text.
c. Gmail Client sends reply via SMTP/Gmail API.
d. Gmail Client moves original message to “gpt-auto-replied” label.
e. SMS Notification Module (new) sends an SMS alert (via Twilio REST API) to a configured phone number, including metadata (sender, subject, timestamp).
5. Loop back to scheduler.

##### Architectural Patterns and Principles
- Single-process event loop/polling model.
- Separation of concerns: polling, filtering, AI processing, email operations, SMS notifications.
- Configuration-driven: behaviors controlled by .env and CSV, minimizing code changes.
- Fail-safe design: local execution, no persistent data; clear exit eliminates data retention.

##### Technologies and Libraries
- Python 3.x / PyInstaller (for .exe)
- python-dotenv (for .env parsing)
- pandas or csv module (for prompt_settings.csv)
- google-api-python-client or imaplib/smtplib (for Gmail)
- openai Python SDK
- twilio Python SDK (for SMS)

##### Final Recommendations
- SMS Notification Module and show how it receives a trigger after email reply.
- Polling intervals and rule evaluation order as annotations if desired.
- Keep the overall flow clear: Inbox → Filter → AI → Reply → Move & SMS.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Windows Host"
        direction TB
        Config["Configuration Store\n(settings.env)"]:::config
        Scheduler["Scheduler/Watcher Service\n(auto_gmail_responder.exe)"]:::internal
        GmailClient["Gmail Client Module"]:::internal
        FilterLoader["Filter & Prompt Loader\n(prompt_settings.csv)"]:::internal
        OpenAIClient["OpenAI Client Module"]:::internal
        SMSModule["SMS Notification Module"]:::internal
        Logs["Local Log Files"]:::store
    end

    subgraph "External Services"
        direction TB
        GmailAPI["Gmail API Endpoint"]:::external
        OpenAIAPI["OpenAI API Endpoint"]:::external
        TwilioAPI["Twilio SMS Service"]:::external
    end

    Config -->|loads| Scheduler
    Scheduler -->|dashed Poll Inbox| GmailClient
    GmailClient -->|gets messages| FilterLoader
    FilterLoader -->|filters messages| Scheduler
    Scheduler -->|matches message| OpenAIClient
    OpenAIClient -->|sync call| OpenAIAPI
    OpenAIAPI -->|returns response| OpenAIClient
    OpenAIClient -->|provides reply| GmailClient
    GmailClient -->|sync send reply| GmailAPI
    GmailClient -->|move to label| GmailAPI
    GmailClient -->|writes logs| Logs
    GmailClient -->|triggers| SMSModule
    SMSModule -->|sync send SMS| TwilioAPI
    SMSModule -->|writes logs| Logs
    Logs -->|stored locally| Logs

    %% Click Events
    click Scheduler "https://github.com/wayswe/auto-gmail-responder/blob/main/auto_gmail_responder.py"
    click FilterLoader "https://github.com/wayswe/auto-gmail-responder/blob/main/prompt_settings.csv"
    click Config "https://github.com/wayswe/auto-gmail-responder/blob/main/settings.env"
    click OpenAIClient "https://github.com/wayswe/auto-gmail-responder/blob/main/auto_gmail_responder.py"
    click GmailClient "https://github.com/wayswe/auto-gmail-responder/blob/main/auto_gmail_responder.py"
    click SMSModule "https://github.com/wayswe/auto-gmail-responder/blob/main/auto_gmail_responder.py"
    click README "https://github.com/wayswe/auto-gmail-responder/blob/main/README.md"
    click LICENSE "https://github.com/wayswe/auto-gmail-responder/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#AEDFFF,stroke:#0288D1,color:#000;
    classDef external fill:#C8E6C9,stroke:#388E3C,color:#000;
    classDef config fill:#FFF9C4,stroke:#FBC02D,color:#000;
    classDef store fill:#ECEFF1,stroke:#546E7A,color:#000;
```
