# sanafagal/whatsapp-sender architecture

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

- Interactive diagram: https://gitdiagram.com/sanafagal/whatsapp-sender
- Repository: https://github.com/sanafagal/whatsapp-sender

## Overview

##### Project type and purpose
- Desktop automation tool built in Python, with a Tkinter GUI, that uses PyAutoGUI to automate WhatsApp Web for bulk messaging.
- Key layers: User Interface, Service/Business Logic, Utilities, External Systems (Browser and WhatsApp Web).

##### File structure
Top-level src/ folders:
- components/ – reusable GUI widgets (app_window.py, ui_components.py)
- config/ – constants (timing, styles)
- services/ – JSON loader (json_service.py) and core messaging orchestration (message_service.py)
- ui/ – high-level UI panels (settings_panel, vendor_panel) and subcomponents (delay_config, log_manager)
- utils/ – low-level helpers (browser_utils.py to launch browsers, json_handler.py, sound_utils.py, time_utils.py)
- app.py – entry point that initializes the UI and wires all modules

##### README for additional insights
- Reads JSON data → vendor queues → config delays → selects browser → clicks “send” → logs progress.
- Technologies: Python, Tkinter, PyAutoGUI, JSON, browser-based WhatsApp Web.

##### Main components & interactions
a. Components
1. GUI Layer
– AppWindow & UI Components (buttons, panels, logs)
– SettingsPanel, VendorPanel
2. Configuration
– constants.py (DEFAULT_DELAYS)
– styles.py (UI theming)
3. JSON Service
– json_service loads/parses file via json_handler
4. Message Service
– Orchestratesreading data + delays + PyAutoGUI actions
5. Utility Layer
– BrowserUtils: launches Edge/Brave/Default
– TimeUtils: computes and enforces delays
– SoundUtils: play success/error beeps
6. External Systems
– Local browser executable
– WhatsApp Web endpoint
b. Interactions (Data-flow)
1. User clicks “Browse & Load” → GUI calls JSON Service → JSON Service uses JSON Handler → returns list of message records
2. User configures delays in SettingsPanel (reads/writes to constants)
3. User selects Vendor → GUI invokes Message Service with selected subset
4. Message Service:
- Calls BrowserUtils to open browser to WhatsApp Web
- Loops messages: uses PyAutoGUI to enter phone+text, send, then TimeUtils delays
- Uses SoundUtils to signal success/failure
- Sends status updates/events back to UI via LogManager
5. GUI LogManager displays progress in real time
c. Architectural patterns & principles
- Layered Architecture (Presentation → Business Logic → Utilities → External)
- Separation of concerns: UI vs services vs utilities vs config
- Single-responsibility per module (e.g., json_service vs message_service)
d. Key technologies
- Python 3.x
- Tkinter for UI
- PyAutoGUI for automation
- JSON for data transport
- Native browser executables

##### Don’t over-complicate

[User Interface (Tkinter)]──calls──> [JSON Service]──uses──> [JSON Handler (util)]
│
└──invokes──> [Message Service]
│
├──calls──> [BrowserUtils]──launches──> [Browser Executable]──connects──> [WhatsApp Web]
├──calls──> [TimeUtils] (delay logic)
├──calls──> [SoundUtils] (feedback)
└──emits logs──> [LogManager]──renders──> [User Interface]

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Entry
    Entry["App Entry (app.py)"]:::service

    subgraph "User Interface"
        AppWindow["AppWindow"]:::frontend
        UIComponents["UIComponents"]:::frontend
        SettingsPanel["SettingsPanel"]:::frontend
        VendorPanel["VendorPanel"]:::frontend
        DelayConfig["DelayConfig"]:::frontend
        LogManager["LogManager"]:::frontend
    end

    subgraph "Configuration"
        Constants["constants.py"]:::config
        Styles["styles.py"]:::config
    end

    subgraph "Service Layer"
        JSONService["JSON Service"]:::service
        MessageService["Message Service"]:::service
    end

    subgraph "Utility Layer"
        JSONHandler["JSON Handler"]:::util
        BrowserUtils["BrowserUtils"]:::util
        TimeUtils["TimeUtils"]:::util
        SoundUtils["SoundUtils"]:::util
    end

    subgraph "External Systems"
        BrowserExec["Browser Executable"]:::external
        WhatsAppWeb["WhatsApp Web"]:::external
    end

    %% Entry wiring
    Entry --> AppWindow
    Entry --> UIComponents
    Entry --> SettingsPanel
    Entry --> VendorPanel

    %% UI to Services
    AppWindow -->|"load JSON"| JSONService
    AppWindow -->|"invoke messaging"| MessageService
    SettingsPanel -->|"read/write"| Constants

    %% Services interactions
    JSONService -->|"parse JSON"| JSONHandler
    MessageService -->|"launch browser"| BrowserUtils
    MessageService -->|"delay"| TimeUtils
    MessageService -->|"audio feedback"| SoundUtils
    MessageService -->|"emit log"| LogManager

    %% Utilities to External
    BrowserUtils -->|"open executable"| BrowserExec
    BrowserExec -->|"navigate"| WhatsAppWeb

    %% UI feedback loop
    LogManager -->|"update UI"| AppWindow

    %% Click Events
    click AppWindow "https://github.com/sanafagal/whatsapp-sender/blob/main/src/components/app_window.py"
    click UIComponents "https://github.com/sanafagal/whatsapp-sender/blob/main/src/components/ui_components.py"
    click SettingsPanel "https://github.com/sanafagal/whatsapp-sender/blob/main/src/ui/panels/settings_panel.py"
    click VendorPanel "https://github.com/sanafagal/whatsapp-sender/blob/main/src/ui/panels/vendor_panel.py"
    click DelayConfig "https://github.com/sanafagal/whatsapp-sender/blob/main/src/ui/components/delay_config.py"
    click LogManager "https://github.com/sanafagal/whatsapp-sender/blob/main/src/ui/components/log_manager.py"
    click Constants "https://github.com/sanafagal/whatsapp-sender/blob/main/src/config/constants.py"
    click Styles "https://github.com/sanafagal/whatsapp-sender/blob/main/src/config/styles.py"
    click JSONService "https://github.com/sanafagal/whatsapp-sender/blob/main/src/services/json_service.py"
    click JSONHandler "https://github.com/sanafagal/whatsapp-sender/blob/main/src/utils/json_handler.py"
    click MessageService "https://github.com/sanafagal/whatsapp-sender/blob/main/src/services/message_service.py"
    click BrowserUtils "https://github.com/sanafagal/whatsapp-sender/blob/main/src/utils/browser_utils.py"
    click TimeUtils "https://github.com/sanafagal/whatsapp-sender/blob/main/src/utils/time_utils.py"
    click SoundUtils "https://github.com/sanafagal/whatsapp-sender/blob/main/src/utils/sound_utils.py"
    click Entry "https://github.com/sanafagal/whatsapp-sender/blob/main/src/app.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#000;
    classDef service fill:#E6FFDD,stroke:#28a745,color:#000;
    classDef util fill:#FFF5B1,stroke:#dbab09,color:#000;
    classDef config fill:#FFDACC,stroke:#d73a49,color:#000;
    classDef external fill:#E5E5E5,stroke:#6a737d,color:#000;
```
