# farzaa/stupid-emails architecture

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

- Interactive diagram: https://gitdiagram.com/farzaa/stupid-emails
- Repository: https://github.com/farzaa/stupid-emails

## Overview

##### Project Type and Purpose
- This is a small, standalone Python script that integrates with two main external services: GMail (via the GMail API) and OpenAI.
- The purpose is to automate the tagging of your GMail emails using a user-customized prompt, where emails are sent to OpenAI and a tag is returned, which is then applied in GMail.
- It’s not a full-stack web application but rather a script focusing on API integration and automation.

##### Analyzing the File Structure
- Key Files:
- tag.py: This is the main script that orchestrates the process.
- prompt.txt: Contains the user prompt for interacting with OpenAI.
- secrets.template.json: A template file where the user’s OpenAI key is configured (renamed to secret.json).
- requirements.txt: Lists the Python dependencies needed by the project.
- README.md and .gitignore: Documentation and version control exclusions.
- The layout shows a self-contained utility script rather than a multi-tiered application. The absence of directories (like frontend/backend or src) indicates that the logic is contained predominantly in tag.py.

##### Components
- Main Application Entry (tag.py): At the center, represent this as the orchestrator of the process.
- External API Integrations:
- GMail API: Show a component labeled “GMail API” through which the script sends authentication requests (using OAuth) and applies email tags.
- OpenAI API: Represent this as a separate component where the script sends email content along with the custom prompt and receives a tagging recommendation.
- Configurations:
- “secret.json” (derived from secrets.template.json): Represent as a configuration component providing the OpenAI key.
- “prompt.txt”: Represent as an input or configuration file that supplies user-specific text.
- Python Dependencies: Mention “requirements.txt” with a note that these libraries support API interactions and any auxiliary processing.

##### Relationships and Data Flow
- The tag.py script first reads the configuration files (secret.json and prompt.txt).
- It then performs Gmail OAuth, establishing a connection with the GMail API for accessing and modifying email data.
- After retrieving the email content (or specific email to tag), tag.py sends this data along with the custom prompt to the OpenAI API.
- OpenAI processes the input and responds with a suggested tag.
- The script then uses the response to tag the relevant email via the GMail API.

##### Architectural Patterns and Design Principles
- Even though the project is simple, it employs a clear separation of concerns:
- Configuration (secrets & prompt files)
- API communication (GMail and OpenAI)
- Core processing (the logic in tag.py handling data and workflow)
- This separation ensures that any modifications (e.g., changing the prompt or updating API handling) remain isolated and easier to manage.
- The design is synchronous and linear, following a sequential set of steps: configuration -> authentication -> API interaction -> result.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    subgraph "Internal Components"
        User["User"]
        Tag["Email Processing Logic (tag.py)"]
        Config["User Configuration (secret.json)"]
        Prompt["User Prompt (prompt.txt)"]
        Dep["Python Dependencies (requirements.txt)"]
    end

    %% External Services
    subgraph "External Services"
        Gmail["GMail API"]
        OpenAI["OpenAI API"]
    end

    %% Relationships and Data Flow
    User -->|"triggers"| Tag
    Config -->|"reads"| Tag
    Prompt -->|"loads"| Tag
    Dep -->|"supports"| Tag
    Tag -->|"OAuth,email retrieval,tag update"| Gmail
    Tag -->|"Email+Prompt->Tag suggestion"| OpenAI

    %% Click Events
    click Tag "https://github.com/farzaa/stupid-emails/blob/main/tag.py"
    click Config "https://github.com/farzaa/stupid-emails/blob/main/secrets.template.json"
    click Prompt "https://github.com/farzaa/stupid-emails/blob/main/prompt.txt"
    click Dep "https://github.com/farzaa/stupid-emails/blob/main/requirements.txt"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef external fill:#F4A460,stroke:#333,stroke-width:2px;
    class User,Tag,Config,Prompt,Dep internal;
    class Gmail,OpenAI external;
```
