# lucasfrusci/whatsapp-bulk-messenger architecture

> Architecture diagram of the GitHub repository lucasfrusci/whatsapp-bulk-messenger, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucasfrusci/whatsapp-bulk-messenger
- Repository: https://github.com/lucasfrusci/whatsapp-bulk-messenger

## Overview

This is a desktop WhatsApp bulk-messaging tool. The user enters recipients and a message, optionally collects contacts from an open group, then starts a paced send through WhatsApp Web; the app reports progress and supports pausing or cancellation. It also filters recipients and saves or loads recipient and message text. The README only describes bulk messaging; the feature details and links below come from the sampled source, not unsampled files.

Main entry points: [`automate.py`](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py) (Send orchestration), [`ui_gui.py`](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/ui_gui.py) (GUI controls), [`contatos.py`](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/contatos.py) (Group contact extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Desktop interface"]
  node_gui["GUI controls<br/>[ui_gui.py]"]
  node_send_logs["Status log<br/>[ui_gui.py]"]
end

subgraph group_messaging["Messaging workflow"]
  node_send_control["Send orchestration<br/>[automate.py]"]
  node_login["WhatsApp login<br/>[automate.py]"]
  node_message_delivery["Message delivery<br/>[automate.py]"]
  node_message_tools["Message editing<br/>[automate.py]"]
end

subgraph group_contact_tools["Contact tools"]
  node_contact_extraction["Group contact extraction<br/>[contatos.py]"]
  node_recipient_tools["Recipient editing<br/>[automate.py]"]
end

subgraph group_local_state["Local state"]
  node_text_files["Message and number files<br/>[automate.py]"]
end

node_user(("User"))
node_chrome["Chrome browser"]
node_whatsapp_web["WhatsApp Web"]

node_user -->|"uses"| node_gui
node_gui -->|"starts or controls"| node_send_control
node_gui -->|"edits recipients"| node_recipient_tools
node_gui -->|"edits message"| node_message_tools
node_gui -->|"requests collection"| node_contact_extraction
node_send_control -->|"reads inputs"| node_gui
node_send_control -->|"reports status"| node_send_logs
node_send_logs -->|"shows updates"| node_user
node_send_control -->|"starts login"| node_login
node_send_control -->|"runs sending"| node_message_delivery
node_send_control -->|"starts scan thread"| node_contact_extraction
node_contact_extraction -->|"adds contacts"| node_gui
node_recipient_tools -->|"saves or loads"| node_text_files
node_message_tools -->|"saves or loads"| node_text_files
node_send_control -->|"loads saved inputs"| node_text_files
node_login -->|"launches"| node_chrome
node_message_delivery -->|"drives browser"| node_chrome
node_contact_extraction -->|"queries page DOM"| node_chrome
node_login -->|"opens site"| node_whatsapp_web
node_message_delivery -->|"opens send URL"| node_whatsapp_web

click node_gui "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/ui_gui.py"
click node_send_logs "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/ui_gui.py"
click node_send_control "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"
click node_login "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"
click node_message_delivery "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"
click node_contact_extraction "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/contatos.py"
click node_recipient_tools "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"
click node_message_tools "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"
click node_text_files "https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gui,node_send_logs,node_user,node_chrome toneBlue
class node_send_control,node_login,node_message_delivery,node_message_tools toneAmber
class node_contact_extraction,node_recipient_tools toneMint
class node_text_files toneRose
class node_whatsapp_web toneIndigo
```

## Components

### Desktop interface

- [GUI controls](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/ui_gui.py): `ui_gui.py`
- [Status log](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/ui_gui.py): `ui_gui.py`

### Messaging workflow

- [Send orchestration](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`
- [WhatsApp login](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`
- [Message delivery](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`
- [Message editing](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`

### Contact tools

- [Group contact extraction](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/contatos.py): `contatos.py`
- [Recipient editing](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`

### Local state

- [Message and number files](https://github.com/lucasfrusci/whatsapp-bulk-messenger/blob/main/automate.py): `automate.py`

### Other components

- **User**
- **Chrome browser**
- **WhatsApp Web**

## Connections

- User → GUI controls: uses (evidence: `ui_gui.py`)
- GUI controls → Send orchestration: starts or controls (evidence: `ui_gui.py`)
- GUI controls → Recipient editing: edits recipients (evidence: `ui_gui.py`)
- GUI controls → Message editing: edits message (evidence: `ui_gui.py`)
- GUI controls → Group contact extraction: requests collection (evidence: `ui_gui.py`)
- Send orchestration → GUI controls: reads inputs (evidence: `automate.py`)
- Send orchestration → Status log: reports status (evidence: `automate.py`)
- Status log → User: shows updates (evidence: `ui_gui.py`)
- Send orchestration → WhatsApp login: starts login (evidence: `automate.py`)
- Send orchestration → Message delivery: runs sending (evidence: `automate.py`)
- Send orchestration → Group contact extraction: starts scan thread (evidence: `automate.py`)
- Group contact extraction → GUI controls: adds contacts (evidence: `contatos.py`)
- Recipient editing → Message and number files: saves or loads (evidence: `automate.py`)
- Message editing → Message and number files: saves or loads (evidence: `automate.py`)
- Send orchestration → Message and number files: loads saved inputs (evidence: `automate.py`)
- WhatsApp login → Chrome browser: launches (evidence: `automate.py`)
- Message delivery → Chrome browser: drives browser (evidence: `automate.py`)
- Group contact extraction → Chrome browser: queries page DOM (evidence: `contatos.py`)
- WhatsApp login → WhatsApp Web: opens site (evidence: `automate.py`)
- Message delivery → WhatsApp Web: opens send URL (evidence: `automate.py`)