# noor-fatima-afzal/cold-email-automation architecture

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

- Interactive diagram: https://gitdiagram.com/noor-fatima-afzal/cold-email-automation
- Repository: https://github.com/noor-fatima-afzal/cold-email-automation

## Overview

##### Project Type and Purpose
- This is an AI-driven automation tool for faculty data scraping and personalized email campaigns.
- It’s not a traditional web app but a Python-based pipeline/orchestration project leveraging LangChain and Groq LLMs.
- Two execution modes:
- Agent-based (autonomous, LangChain agent)
- Sequential (step-by-step pipeline)

##### File Structure Analysis
- Top level:
- main.py       – entrypoint, parses args, kicks off workflows
- config.py     – configuration (endpoints, credentials, test mode flags)
- llm_setup.py  – initializes Groq LLM & LangChain client
- tools/: domain helpers
- email_campaign.py – templates + SMTP/test inbox logic
- faculty_scraper.py – HTTP requests + HTML parsing + CSV output
- workflows/: orchestration
- agent_workflow.py      – LangChain Agent setup + autonomous loop
- sequential_workflow.py – linear pipeline steps

##### Key Components
- User/CLI: triggers main.py with mode flag
- Config Module: centralizes API keys, SMTP settings, test flags
- LLM Layer: groq “gemma2-9b-it” via LangChain client
- Scraper Tool: fetch & parse university site → CSV
- Email Tool: generate email bodies via LLM → send via SMTP/test inbox
- Workflows:
- Agent Workflow: Agent interacts with scraper/email tools autonomously
- Sequential Workflow: Controller invokes scraper → LLM → email in series
- External Systems:
- University Website (HTTP)
- SMTP Server or Test Inbox
- Groq LLM API

##### Relationships & Data Flows
- main.py → loads config.py & llm_setup.py
- main.py → selects and invokes either agent_workflow or sequential_workflow
- Workflow → calls faculty_scraper (outputs CSV)
- Workflow → calls email_campaign (pulls CSV, generates emails via LLM, dispatches)
- LLM setup (llm_setup.py) is injected into both workflows and tools
- Tools depend on config for endpoints, credentials, test mode

##### Architectural Patterns & Principles
- Modular layering:
- Orchestration layer (workflows)
- Tool/domain logic layer (tools)
- Infrastructure/configuration layer (config & llm_setup)
- Dependency Injection: workflows and tools receive LLM client and config
- Two modes illustrate:
- Agent pattern (LangChain agent loop)
- Sequential pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    Main["main.py"]:::core
    Config["config.py"]:::core
    LLMSetup["llm_setup.py"]:::core

    Main -->|"loads"| Config
    Main -->|"initializes"| LLMSetup
    Main -->|"selects mode"| AgentWF
    Main -->|"selects mode"| SeqWF

    subgraph "Workflows"
        AgentWF["Agent Workflow"]:::workflow
        SeqWF["Sequential Workflow"]:::workflow
    end

    AgentWF -->|"injects config"| Config
    AgentWF -->|"injects LLM client"| LLMSetup
    AgentWF -->|"calls"| Scraper
    AgentWF -->|"calls"| EmailTool

    SeqWF -->|"injects config"| Config
    SeqWF -->|"injects LLM client"| LLMSetup
    SeqWF -->|"calls"| Scraper
    SeqWF -->|"calls"| EmailTool

    subgraph "Tools"
        Scraper["Scraper Tool"]:::tool
        EmailTool["Email Tool"]:::tool
    end

    Scraper -->|HTTP request| UnivWeb
    UnivWeb["University Website"]:::external
    Scraper -->|outputs CSV| CSV[/"Faculty CSV"/]:::artifact

    EmailTool -->|reads CSV| CSV
    EmailTool -->|"generate via LLM"| LLMAPI
    LLMAPI["Groq LLM API"]:::external
    EmailTool -->|SMTP/Test inbox| SMTP["SMTP Server/Test Inbox"]:::external

    %% Click Events
    click Main "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/main.py"
    click Config "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/config.py"
    click LLMSetup "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/llm_setup.py"
    click Scraper "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/tools/faculty_scraper.py"
    click EmailTool "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/tools/email_campaign.py"
    click AgentWF "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/workflows/agent_workflow.py"
    click SeqWF "https://github.com/noor-fatima-afzal/cold-email-automation/blob/main/workflows/sequential_workflow.py"

    %% Styles
    classDef core fill:#DDEEFF,stroke:#000,stroke-width:1px
    classDef tool fill:#EEFFDD,stroke:#000,stroke-width:1px
    classDef workflow fill:#FFEEDD,stroke:#000,stroke-width:1px
    classDef external fill:#EEEEEE,stroke:#000,stroke-width:1px
    classDef artifact fill:#F0F0F0,stroke-dasharray:2 2,stroke:#000
```
