# prakhar619/coldcontactxlsx architecture

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

- Interactive diagram: https://gitdiagram.com/prakhar619/coldcontactxlsx
- Repository: https://github.com/prakhar619/coldcontactxlsx

## Overview

##### Project Type and Purpose
- This is a CLI-driven “automation” tool (Python script) that reads recruiter data from an Excel spreadsheet, generates possible recruiter email addresses, composes personalized cold emails (with optional follow-ups), and sends them in batches according to a schedule.
- There is no user-facing GUI or persistent database; the primary I/O artifacts are spreadsheets, email templates, logs, and the SMTP service.

##### File Structure
Top-level:
- main.py – orchestrates the workflow.
- .env – holds SMTP credentials, user details, email subject/body variables.
- requirements.txt – Python dependencies (e.g., openpyxl, smtplib).
- readme.md – project overview and instructions.

Directories:
- email_template – contains “email_template.txt” and “follow_up_template.txt”.
- resumes – holds PDF resumes to attach.
- utils
– data_utils
- excel_reader.py – reads and parses the recruiters.xlsx file.
- generate_email_address.py – applies common company email patterns to guess addresses.
– email_utils
- email_manager.py – assembles the email content (templating + attachments).
- email_sender.py – handles SMTP connection, retries, and error handling.
- follow_up.py – tracks sent emails and composes follow-ups for non-responders.
– scheduler
- schedule_now.py – triggers immediate send.
- send_later.py – schedules a future send time (batch/time-based control).

Supporting files:
- recruiters.xlsx – input data.
- logs – records successful sends and errors.

##### README for Additional Insights
- Features: bulk sending, scheduling, retry logic, follow-ups, attachment support.
- Future TODO: Chrome extension, OpenAI integration—but out of current scope.

##### Main Components & Interactions
a. Data Input
– recruiters.xlsx (Excel) → data_utils.excel_reader reads rows.
b. Email Address Generation
– data_utils.generate_email_address applies patterns per row.
c. Email Content Assembly
– email_template/*.txt + .env variables + resume attachment → email_utils.email_manager.
d. Sending & Scheduling
– scheduler.schedule_now or send_later determines send timing.
– email_utils.email_sender connects to SMTP (external service) & sends.
e. Follow-Up Logic
– email_utils.follow_up identifies non-responders and re-uses templates.
f. Logging
– successes & failures written to logs/*.txt.

##### Architectural Patterns & Design Principles
- Modular layering:
– Data Layer (Excel reader, address generator)
– Business Logic (email manager, scheduler, follow-up)
– Infrastructure Layer (SMTP client, retry logic, logging)
- Single responsibility per module, clear separation of concerns.
- CLI orchestration in main.py.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point
    Main[/"main.py (CLI Orchestration)"/]:::entry
    Env[".env (Configuration)"]:::config

    %% Input Layer
    subgraph "Input Layer" 
        direction TB
        Excel["Recruiters.xlsx"]:::datafile
        Templates["Email Templates"]:::templates
        FollowUpTemplate["follow_up_template.txt"]:::templates
        Resumes["resumes/ (Attachments)"]:::attachments
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ExcelReader["ExcelReader"]:::datalayer
        AddressGen["EmailAddressGenerator"]:::datalayer
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        direction TB
        EmailManager["EmailManager"]:::bizlogic
        FollowUpLogic["FollowUpLogic"]:::bizlogic
    end

    %% Scheduling Layer
    subgraph "Scheduling"
        direction TB
        ScheduleNow["ScheduleNow"]:::scheduler
        SendLater["SendLater"]:::scheduler
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        direction TB
        EmailSender["EmailSender\n(3× retry on failure)"]:::infrastructure
        Logging["Logging Service\n(logs/)"]:::infrastructure
    end

    %% External Services
    subgraph "External"
        direction TB
        SMTP["SMTP Service"]:::external
    end

    %% Connections
    Main -->|reads config| Env
    Main -->|orchestrates| Excel
    Excel -->|reads rows| ExcelReader
    ExcelReader -->|provides data| AddressGen
    AddressGen -->|guesses emails| EmailManager
    Env -->|provides vars| EmailManager
    Templates -->|loads template| EmailManager
    EmailManager -->|assembles email| ScheduleNow
    EmailManager -->|assembles email| SendLater
    Resumes -->|attaches| EmailManager

    ScheduleNow -->|triggers send| EmailSender
    SendLater -->|schedules send| EmailSender
    EmailSender -->|sends SMTP request| SMTP
    EmailSender -->|logs result| Logging

    Logging -->|reads non-responders| FollowUpLogic
    FollowUpLogic -->|composes follow-up| EmailSender
    Env -->|provides vars| EmailSender

    %% Click Events
    click Main "https://github.com/prakhar619/coldcontactxlsx/blob/main/main.py"
    click Env "https://github.com/prakhar619/coldcontactxlsx/blob/main/.env"
    click Excel "https://github.com/prakhar619/coldcontactxlsx/blob/main/recruiters.xlsx"
    click Templates "https://github.com/prakhar619/coldcontactxlsx/tree/main/email_template"
    click FollowUpTemplate "https://github.com/prakhar619/coldcontactxlsx/blob/main/email_template/follow_up_template.txt"
    click ExcelReader "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/data_utils/excel_reader.py"
    click AddressGen "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/data_utils/generate_email_address.py"
    click EmailManager "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/email_utils/email_manager.py"
    click FollowUpLogic "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/email_utils/follow_up.py"
    click EmailSender "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/email_utils/email_sender.py"
    click ScheduleNow "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/scheduler/schedule_now.py"
    click SendLater "https://github.com/prakhar619/coldcontactxlsx/blob/main/utils/scheduler/send_later.py"
    click Resumes "https://github.com/prakhar619/coldcontactxlsx/tree/main/resumes/"
    click Logging "https://github.com/prakhar619/coldcontactxlsx/tree/main/logs/"

    %% Styles
    classDef entry fill:#FFD700,stroke:#333,stroke-width:1px
    classDef config fill:#FFECB3,stroke:#333,stroke-width:1px
    classDef datafile fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef templates fill:#B3E5FC,stroke:#333,stroke-width:1px
    classDef attachments fill:#B2DFDB,stroke:#333,stroke-width:1px
    classDef datalayer fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef bizlogic fill:#FFF9C4,stroke:#333,stroke-width:1px
    classDef scheduler fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef infrastructure fill:#FFCCBC,stroke:#333,stroke-width:1px
    classDef external fill:#CFD8DC,stroke:#333,stroke-width:1px
```
