# rushi-ship/whatsapp_groups-automation architecture

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

- Interactive diagram: https://gitdiagram.com/rushi-ship/whatsapp_groups-automation
- Repository: https://github.com/rushi-ship/whatsapp_groups-automation

## Overview

##### Project type and purpose
- This is a small full-stack web application (“WhatsApp Automation Tool”) built on Python/Flask.
- Purpose: provide a secure web UI for uploading Excel files of group data and sending either generic or stock-recommendation messages to WhatsApp groups via an automated browser (ChromeDriver).

##### File structure
- app.py: main Flask application (routes, view logic).
- init_db.py: script to initialize the user credentials database.
- whatsapp_utils.py: module encapsulating all WhatsApp-automation logic (launching ChromeDriver, navigating WhatsApp Web, sending messages).
- templates/: Jinja2 templates (login.html, index.html for message selection, base.html).
- requirements.txt: dependencies (Flask, Selenium, openpyxl or pandas, etc.).
- README.md: documents features, usage, Excel format, security.

##### README for additional insights
- Security: user login, password hashing, session management.
- Excel upload: two modes (generic vs. stock).
- Dependencies: Python 3.8+, Flask, ChromeDriver.

##### Main components & interactions
a. Components:
- Client Browser (Web UI)
- Flask Web Server (app.py)
- Database (SQLite via init_db.py)
- Excel Parser (built into app.py or whatsapp_utils)
- WhatsApp Automation Service (whatsapp_utils.py using Selenium/ChromeDriver)
- External Service: WhatsApp Web

b. Relationships / data ﬂow:
1. User opens browser → requests login page (Flask).
2. User submits credentials → Flask validates against Database.
3. Upon login, user uploads Excel → Flask parses file, validates columns.
4. User selects message type → Flask passes data to whatsapp_utils.
5. whatsapp_utils spins up ChromeDriver → logs in to WhatsApp Web UI → iterates through rows, sends messages.
6. Completion status returns to Flask → shown in browser.

c. Architectural patterns / principles:
- MVC-style separation: Templates (View), app.py (Controller), Database/Utilities (Model & Services).
- Single-responsibility: whatsapp_utils.py strictly handles messaging logic.
- Modular: Database init & management separated to init_db.py.

d. Key technologies:
- Flask & Jinja2 for web server and templating.
- SQLite (or other relational DB) for user credentials.
- Selenium WebDriver (ChromeDriver) for browser automation.
- openpyxl or pandas (in requirements.txt) for Excel parsing.

- Flask and its sub-components (auth, file upload, business logic) in the Web Server layer.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        UserBrowser["User Browser"]:::external
        ExcelFile["Excel File"]:::data
    end

    %% Web Server Layer
    subgraph "Web Server Layer"
        App["Flask Server\n(app.py)"]:::service
        InitDB["DB Init Script\n(init_db.py)"]:::service
        subgraph "View Templates"
            Base["base.html"]:::service
            Login["login.html"]:::service
            Index["index.html"]:::service
        end
    end

    %% Database
    Database["Database\n(SQLite)"]:::db

    %% Services Layer
    subgraph "Services Layer"
        ExcelParser["Excel Parser\n(whatsapp_utils.py)"]:::service
        WhatsAppService["WhatsApp Automation\n(whatsapp_utils.py)"]:::service
        ChromeDriver["ChromeDriver"]:::service
    end

    %% External Systems
    WhatsAppWeb["WhatsApp Web"]:::external

    %% Other Components
    Requirements["requirements.txt"]:::data
    Docs["README.md"]:::data

    %% Connections
    UserBrowser -->|"GET /login"| App
    UserBrowser -->|"POST /login"| App
    App -->|"SELECT user"| Database
    App -->|"RENDER login"| UserBrowser
    App -->|"RENDER index"| UserBrowser

    UserBrowser -->|"UPLOAD Excel"| App
    App -->|"CALL parse_excel()"| ExcelParser
    ExcelParser -->|"PARSED DATA"| App

    App -->|"CALL send_messages()"| WhatsAppService
    WhatsAppService -->|"LAUNCH"| ChromeDriver
    ChromeDriver -->|"NAVIGATE & SEND"| WhatsAppWeb
    WhatsAppService -->|"RETURN status"| App
    App -->|"DISPLAY status"| UserBrowser

    InitDB -->|"INITIALIZE"| Database

    %% Click Events
    click App "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/app.py"
    click InitDB "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/init_db.py"
    click ExcelParser "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/whatsapp_utils.py"
    click WhatsAppService "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/whatsapp_utils.py"
    click Base "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/templates/base.html"
    click Login "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/templates/login.html"
    click Index "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/templates/index.html"
    click Requirements "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/requirements.txt"
    click Docs "https://github.com/rushi-ship/whatsapp_groups-automation/blob/main/README.md"

    %% Styles
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#9f6,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
```
