# arsath-mohamed/ai-cold-email-generator architecture

> Architecture diagram of the GitHub repository arsath-mohamed/ai-cold-email-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arsath-mohamed/ai-cold-email-generator
- Repository: https://github.com/arsath-mohamed/ai-cold-email-generator

## Overview

This Streamlit app turns freelancer and target details plus scraped public-page context into an editable personalized cold email, then can send it through Gmail. The main path is user input → scraping and context assembly → Groq generation → review/edit → Gmail delivery. The source excerpts show the app’s calls and service integrations; no separate persistence subsystem is evident beyond Gmail OAuth token files.

Main entry points: [`app.py`](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py) (App workflow), [`scraper.py`](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/scraper.py) (Page scraper), [`gmail.py`](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/gmail.py) (Gmail sender), [`llm.py`](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/llm.py) (Email generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Streamlit workflow"]
  node_app["App workflow<br/>[app.py]"]
  node_context["Context assembly<br/>[app.py]"]
  node_review["Review and edit<br/>[app.py]"]
  node_clipboard["Clipboard copy<br/>[app.py]"]
end

subgraph group_research["Target research"]
  node_scraper["Page scraper<br/>[scraper.py]"]
end

subgraph group_generation["Email generation"]
  node_generator["Email generator<br/>[llm.py]"]
end

subgraph group_delivery["Gmail delivery"]
  node_gmail_sender["Gmail sender<br/>[gmail.py]"]
  node_oauth[("OAuth credentials<br/>[gmail.py]")]
end

node_freelancer(("Freelancer"))
node_website{{"Target website"}}
node_groq{{"Groq API"}}
node_gmail_api{{"Gmail API"}}
node_recipient(("Email recipient"))

node_freelancer -->|"enters details"| node_app
node_app -->|"fetches context"| node_scraper
node_scraper -->|"requests page"| node_website
node_scraper -->|"returns page data"| node_context
node_app -->|"assembles inputs"| node_context
node_app -->|"requests draft"| node_generator
node_generator -->|"generates text"| node_groq
node_app -->|"displays draft"| node_review
node_review -->|"copies text"| node_clipboard
node_recipient -->|"enters address"| node_app
node_app -->|"sends reviewed email"| node_gmail_sender
node_gmail_sender -->|"loads or saves tokens"| node_oauth
node_gmail_sender -->|"submits message"| node_gmail_api

click node_app "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py"
click node_scraper "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/scraper.py"
click node_context "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py"
click node_generator "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/llm.py"
click node_review "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py"
click node_clipboard "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py"
click node_gmail_sender "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/gmail.py"
click node_oauth "https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/gmail.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_context,node_review,node_clipboard toneBlue
class node_scraper toneAmber
class node_generator,node_groq,node_gmail_api toneMint
class node_gmail_sender,node_oauth toneRose
class node_freelancer,node_website,node_recipient toneIndigo
```

## Components

### Streamlit workflow

- [App workflow](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py): `app.py`
- [Context assembly](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py): `app.py`
- [Review and edit](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py): `app.py`
- [Clipboard copy](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/app.py): `app.py`

### Target research

- [Page scraper](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/scraper.py): `scraper.py`

### Email generation

- [Email generator](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/llm.py): `llm.py`

### Gmail delivery

- [Gmail sender](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/gmail.py): `gmail.py`
- [OAuth credentials](https://github.com/arsath-mohamed/ai-cold-email-generator/blob/main/gmail.py): `gmail.py`

### Other components

- **Freelancer**
- **Target website**
- **Groq API**
- **Gmail API**
- **Email recipient**

## Connections

- Freelancer → App workflow: enters details (evidence: `app.py`)
- App workflow → Page scraper: fetches context (evidence: `app.py`)
- Page scraper → Target website: requests page (evidence: `scraper.py`)
- Page scraper → Context assembly: returns page data (evidence: `app.py`)
- App workflow → Context assembly: assembles inputs (evidence: `app.py`)
- App workflow → Email generator: requests draft (evidence: `app.py`)
- Email generator → Groq API: generates text (evidence: `llm.py`)
- App workflow → Review and edit: displays draft (evidence: `app.py`)
- Review and edit → Clipboard copy: copies text (evidence: `app.py`)
- Email recipient → App workflow: enters address (evidence: `app.py`)
- App workflow → Gmail sender: sends reviewed email (evidence: `app.py`)
- Gmail sender → OAuth credentials: loads or saves tokens (evidence: `gmail.py`)
- Gmail sender → Gmail API: submits message (evidence: `gmail.py`)
