# wkl-sec/warmer architecture

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

- Interactive diagram: https://gitdiagram.com/wkl-sec/warmer
- Repository: https://github.com/wkl-sec/warmer

## Overview

##### Project type and purpose
- This is an open-source, stand-alone Python CLI tool (Warmer.py) whose sole purpose is to automate “warming up” an Outlook/Office365 email account. It uses Selenium WebDriver to drive the Outlook web interface, sending a configurable number of emails to one or more targets.

##### File structure
- Top-level files only:
- Warmer.py – entry point and core logic
- requirements.txt – third-party dependencies (e.g., selenium, email-related libs)
- README.md, LICENSE
- No frontend/backend split, no persistent datastore—just a single script orchestrating browser automation.

##### Extract key architecture insights from the README
- Configuration via CLI flags: sender credentials, single vs. multi-target mode, number of emails, content mode (gibberish, AI-generated, template).
- Supports reading a wordlist file for multiple targets.
- Relies on Selenium-driven browser (Chrome/Firefox) to log into Outlook Web and send messages.

##### Main components
a. CLI Argument Parser
- Parses -u, -p, -T/-t, -x, -m flags.
b. Input Manager
- Loads single target or parses send_to_list.txt.
c. Content Generation Module
- Mode 1: gibberish sentence generator
- Mode 2: calls out to an AI-generation library or API
- Mode 3: picks from a set of pre-defined templates
d. Selenium Automation Core
- Instantiates WebDriver (ChromeDriver/GeckoDriver)
- Logs into Outlook/Office365 Web UI using provided credentials
- Navigates to “New Email,” populates To/Subject/Body, and sends
- Handles looping for N messages and multiple targets
e. External Service: Outlook Web (Office365)
- The target web application that actually delivers emails
f. Optional: Local Resources
- send_to_list.txt (multi-target list)
- template files (if stored externally)
g. Logging & Error Handling
- Captures success/failure per message, retry logic (if implemented)

##### Relationships and data flow
- The CLI Parser feeds configuration into the Input Manager and Content Generator.
- Input Manager produces a target list.
- A loop invokes Content Generator to obtain each email body.
- Selenium Automation Core uses those inputs to drive the web browser and send emails to Outlook Web.
- Logging captures each send result.

##### Architectural patterns & design principles
- Single-Responsibility: separate modules for parsing, input reading, content generation, and browser automation.
- Dependency clarity: requirements.txt lists exactly which libraries (e.g., selenium) are needed.
- Extensibility point: adding new content modes or supporting another email provider should map to new modules behind the Content Generation or Automation interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI Argument Parser"]:::internal
    Input["Input Manager"]:::internal
    Content["Content Generation Module"]:::internal
    Selenium["Selenium Automation Core"]:::internal
    Outlook["Outlook Web (Office365)"]:::external
    Logging["Logging & Error Handling"]:::internal
    Resources["Local Resources\n(send_to_list.txt, templates)"]:::resource
    Deps["requirements.txt"]:::doc
    ReadMe["README.md"]:::doc
    License["LICENSE"]:::doc

    CLI -->|"parses flags"| Input
    CLI -->|"parses flags"| Content
    Resources -->|"loads targets"| Input
    Resources -->|"loads templates"| Content
    Input -->|"target list"| Selenium
    Content -->|"email body"| Selenium
    Selenium -->|"sends emails"| Outlook
    Selenium -->|"logs results"| Logging
    Selenium -->|"retry logic"| Logging

    classDef internal fill:#d4f1c5,stroke:#4caf50,color:#000
    classDef external fill:#cce5ff,stroke:#31708f,color:#000
    classDef resource fill:#fff3cd,stroke:#856404,color:#000
    classDef doc fill:#e2e3e5,stroke:#6c757d,color:#000

    click CLI "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Input "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Content "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Selenium "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Outlook "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Logging "https://github.com/wkl-sec/warmer/blob/main/Warmer.py"
    click Deps "https://github.com/wkl-sec/warmer/blob/main/requirements.txt"
    click ReadMe "https://github.com/wkl-sec/warmer/blob/main/README.md"
    click License "https://github.com/wkl-sec/warmer/tree/main/LICENSE"
```
