# aiwithhassan/cold-email-generator architecture

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

- Interactive diagram: https://gitdiagram.com/aiwithhassan/cold-email-generator
- Repository: https://github.com/aiwithhassan/cold-email-generator

## Overview

This Streamlit app turns a submitted job-posting URL into one or more tailored cold emails. Its main workflow fetches and cleans the page, extracts job details with an LLM, retrieves matching portfolio links, and asks the LLM to draft emails for display. The graph separates orchestration, text preparation, model work, and portfolio retrieval. Source excerpts show these calls; external service behavior is represented only where the code invokes it.

Main entry points: [`main.py`](https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py) (Streamlit app), [`chains.py`](https://github.com/aiwithhassan/cold-email-generator/blob/main/chains.py) (Email drafting), [`portfolio.py`](https://github.com/aiwithhassan/cold-email-generator/blob/main/portfolio.py) (Portfolio lookup), [`utils.py`](https://github.com/aiwithhassan/cold-email-generator/blob/main/utils.py) (Text cleaning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App workflow"]
  node_app["Streamlit app<br/>[main.py]"]
  node_fetch["Page loader<br/>[main.py]"]
  node_clean["Text cleaning<br/>[utils.py]"]
  node_email["Generated email<br/>[main.py]"]
end

subgraph group_ai["Language model"]
  node_extract["Job extraction<br/>[chains.py]"]
  node_model["ChatGroq model"]
  node_draft["Email drafting<br/>[chains.py]"]
end

subgraph group_portfolio["Portfolio retrieval"]
  node_portfolio["Portfolio lookup<br/>[portfolio.py]"]
  node_csv["Portfolio CSV"]
  node_store[("Portfolio vector store")]
end

node_user(("User"))

node_user -->|"submits URL"| node_app
node_app -->|"loads page"| node_fetch
node_fetch -->|"passes page text"| node_clean
node_app -->|"extracts jobs"| node_extract
node_extract -->|"invokes model"| node_model
node_app -->|"loads and queries"| node_portfolio
node_portfolio -->|"reads records"| node_csv
node_portfolio -->|"adds and queries"| node_store
node_app -->|"requests email"| node_draft
node_draft -->|"invokes model"| node_model
node_draft -->|"returns draft"| node_email
node_email -->|"displays email"| node_user

click node_app "https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py"
click node_fetch "https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py"
click node_clean "https://github.com/aiwithhassan/cold-email-generator/blob/main/utils.py"
click node_extract "https://github.com/aiwithhassan/cold-email-generator/blob/main/chains.py"
click node_portfolio "https://github.com/aiwithhassan/cold-email-generator/blob/main/portfolio.py"
click node_csv "https://github.com/aiwithhassan/cold-email-generator/blob/main/sample_portfolio.csv"
click node_store "https://github.com/aiwithhassan/cold-email-generator/tree/main/vectorstore2"
click node_draft "https://github.com/aiwithhassan/cold-email-generator/blob/main/chains.py"
click node_email "https://github.com/aiwithhassan/cold-email-generator/blob/main/main.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_fetch,node_clean,node_email,node_user toneBlue
class node_extract,node_model,node_draft toneAmber
class node_portfolio,node_csv,node_store toneMint
```

## Components

### App workflow

- [Streamlit app](https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py): `main.py`
- [Page loader](https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py): `main.py`
- [Text cleaning](https://github.com/aiwithhassan/cold-email-generator/blob/main/utils.py): `utils.py`
- [Generated email](https://github.com/aiwithhassan/cold-email-generator/blob/main/main.py): `main.py`

### Language model

- [Job extraction](https://github.com/aiwithhassan/cold-email-generator/blob/main/chains.py): `chains.py`
- **ChatGroq model**
- [Email drafting](https://github.com/aiwithhassan/cold-email-generator/blob/main/chains.py): `chains.py`

### Portfolio retrieval

- [Portfolio lookup](https://github.com/aiwithhassan/cold-email-generator/blob/main/portfolio.py): `portfolio.py`
- [Portfolio CSV](https://github.com/aiwithhassan/cold-email-generator/blob/main/sample_portfolio.csv): `sample_portfolio.csv`
- [Portfolio vector store](https://github.com/aiwithhassan/cold-email-generator/tree/main/vectorstore2): `vectorstore2`

### Other components

- **User**

## Connections

- User → Streamlit app: submits URL (evidence: `main.py`)
- Streamlit app → Page loader: loads page (evidence: `main.py`)
- Page loader → Text cleaning: passes page text (evidence: `main.py`)
- Streamlit app → Job extraction: extracts jobs (evidence: `main.py`)
- Job extraction → ChatGroq model: invokes model (evidence: `chains.py`)
- Streamlit app → Portfolio lookup: loads and queries (evidence: `main.py`)
- Portfolio lookup → Portfolio CSV: reads records (evidence: `portfolio.py`)
- Portfolio lookup → Portfolio vector store: adds and queries (evidence: `portfolio.py`)
- Streamlit app → Email drafting: requests email (evidence: `main.py`)
- Email drafting → ChatGroq model: invokes model (evidence: `chains.py`)
- Email drafting → Generated email: returns draft (evidence: `main.py`)
- Generated email → User: displays email (evidence: `main.py`)
