# yash-meshram/cold-email-generator architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack AI-powered web application (“Cold Email Generator”) with a Streamlit frontend, Python backend logic written with LangChain, and a local vector database (ChromaDB) for portfolio matching. Its purpose is to scrape job postings, vectorize your portfolio, query the vector store, and use an LLM (via Groq) to generate personalized cold emails.

##### File structure
- Top-level:
- app/ – main Streamlit entrypoint (main.py), orchestration logic (chains.py), portfolio management (portfolio.py), utilities (utils.py), and static resources (resources/my_portfolio.csv).
- VectorDB/ – persistent ChromaDB storage (SQLite and binary index files).
- testing/ – unit/integration scripts, sample data, and temporary vector store.
- README.md, NOTES.txt, .gitignore.
- Patterns:
- “chains.py” implements a pipeline (filters and transformations).
- “portfolio.py” encapsulates CRUD + vector-store integration.
- “VectorDB/” holds the on-disk vector index.
- Config via environment variables (.env).

##### Extract insights from README
- Frontend: Streamlit UI in app/main.py.
- Backend:
- Web scraper → text cleaning (utils.py) → job parser (chains.py).
- Portfolio ingestion & query using ChromaDB (portfolio.py).
- LLM integration (langchain_groq) for email generation.
- External dependencies: Groq LLM, ChromaDB, Streamlit, LangChain, pandas.

##### Main components and interactions
a. Components:
1. Streamlit UI (app/main.py)
2. Controller/Chain Orchestrator (app/chains.py)
3. Web Scraper & Parser (inside chains.py + utils.py)
4. Portfolio Vector Store (app/portfolio.py + VectorDB/)
5. LLM Service (Groq via LangChain_groq)
6. Data Sources: Career page URLs; app/resources/my_portfolio.csv
b. Relationships & data flow:
- User enters URL in Streamlit UI →
- Main triggers chain: scrape → clean → parse →
- Portfolio module loads/updates vector store → queries for top-N relevant projects →
- Chain calls LLM with job + portfolio context →
- Generated email returned to Streamlit UI.
- Vector store persists to VectorDB/ (SQLite & binary files).
c. Architectural patterns:
- Pipeline (chains of transformations).
- Layered separation: Presentation (Streamlit) → Orchestration (chains.py) → Domain (portfolio.py) → Persistence (ChromaDB) → External (Groq API).
d. Key technologies:
- Python, Streamlit, LangChain, Groq API, ChromaDB (SQLite backend), pandas.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external
    %% Frontend Layer
    UI["Streamlit UI"]:::frontend
    %% Core Logic Layer
    Chains["Chain Orchestrator\n(app/chains.py)"]:::core
    Utils["Web Scraper & Parser\n(app/utils.py & app/chains.py)"]:::core
    Portfolio["Portfolio Module\n(app/portfolio.py)"]:::core
    %% Data Layer
    CSV["Portfolio CSV\n(app/resources/my_portfolio.csv)"]:::data
    VectorDB["ChromaDB Vector Store\n(VectorDB/)"]:::data
    %% External Services
    LLM["Groq LLM API"]:::external

    %% Flows
    User -->|"enter URL"| UI
    UI -->|"trigger pipeline"| Chains
    Chains -->|"scrape HTML"| Utils
    Chains -->|"vector query"| Portfolio
    Portfolio -->|"read/update data"| VectorDB
    Portfolio -->|"read portfolio"| CSV
    Chains -->|"LLM prompt & response"| LLM
    LLM -->|"generated email"| UI

    %% Click Events
    click UI "https://github.com/yash-meshram/cold-email-generator/blob/main/app/main.py"
    click Chains "https://github.com/yash-meshram/cold-email-generator/blob/main/app/chains.py"
    click Utils "https://github.com/yash-meshram/cold-email-generator/blob/main/app/utils.py"
    click Portfolio "https://github.com/yash-meshram/cold-email-generator/blob/main/app/portfolio.py"
    click CSV "https://github.com/yash-meshram/cold-email-generator/blob/main/app/resources/my_portfolio.csv"
    click VectorDB "https://github.com/yash-meshram/cold-email-generator/tree/main/VectorDB/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef core fill:#E6FFEA,stroke:#28a745,color:#22863a;
    classDef data fill:#FFF5B1,stroke:#dca100,color:#735c0f;
    classDef external fill:#F0F0F0,stroke:#6a737d,color:#6a737d;
```
