# sohunn/whatsbulk architecture

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

- Interactive diagram: https://gitdiagram.com/sohunn/whatsbulk
- Repository: https://github.com/sohunn/whatsbulk

## Overview

##### Project Type & Purpose
- The project is a simple Node.js library written in TypeScript. Its purpose is to automate the process of sending bulk messages on WhatsApp by simulating the WhatsApp web interface.
- The README makes it clear that it is designed to be used as a library—not a full-stack application—with a focus on automating WhatsApp web actions using a provided HTML selector.

##### Analyzing the File Structure
- The project files include key configuration files for linting (.eslintrc, .eslintignore), TypeScript (tsconfig.json), and package management (package.json, package-lock.json).
- The source code in the src/ directory includes:
- BulkMessenger.ts – likely contains the core logic for sending messages in bulk.
- index.ts – probably exposed as the main entry point when the package is required.
- types.ts – defines TypeScript types such as BulkMessengerConfig and BulkMessengerResults.
- The file structure indicates a small, tightly focused library with clearly defined responsibilities.

##### Extracting Architectural Insights from the README
- The README explains that the BulkMessenger library provides a configuration-driven API, where you pass in an array of phone numbers, a message, and an HTML selector.
- The library initiates by opening a WhatsApp web session (requiring an initial QR-based login) and then iterates over the phone numbers.
- It fires events (message, error, end) to notify the calling code about the success or failure of each messaging attempt.
- The library uses timing configurations (intervals and selector wait timeouts) to control interactions.

##### Main Components
a. User Application Code:
- Represents the code that imports and uses the BulkMessenger library.
- Shows configuration objects and event listeners (for message, error, end).

b. BulkMessenger Component:
- The core library class (BulkMessenger) encapsulates the business logic.
- It processes the configuration, manages iteration over numbers, and handles delays (via interval and timeout settings).
- Contains an event emitter to signal status updates back to the user code.

c. WhatsApp Web Interface:
- Represents the external WhatsApp web session the library controls.
- Includes a browser automation layer where the library interacts with the WhatsApp webpage (waiting for the provided HTML selector).
- Initial login authentication process (triggered on the first run) and subsequent reuse of class names until logout.

d. Event Manager:
- Although integrated within BulkMessenger, this component is important since it routes events (successful message sending, errors, and completion) to the user-defined callbacks.

##### Relationships & Data Flow
- The User Application invokes BulkMessenger by passing in a configuration.
- BulkMessenger initiates a WhatsApp web session (if not already logged in) and “watches” for the HTML element (using the provided selector) to ensure that WhatsApp is ready for interaction.
- For each phone number:
- BulkMessenger sends the message.
- Event triggers are emitted: “message” on success, “error” on failure.
- After processing all numbers, an “end” event is emitted with a results object detailing the successes and failures.

##### Architectural Patterns & Principles
- The library follows an event-driven design, making heavy use of Node.js’s event emitter pattern.
- It abstracts the complexities of web automation within a single component (BulkMessenger), enforcing separation of concerns.
- The design includes configurable timing parameters, displaying a focus on robustness when interfacing with an external service (WhatsApp web).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Application Layer"
        UA["User Application Code"]:::user
        API["Public API"]:::library
    end

    subgraph "Library Layer"
        BM["BulkMessenger Component"]:::library
        EM["Event Manager"]:::library
        TD["Type Definitions"]:::library
    end

    subgraph "External Services"
        WA["WhatsApp Web Session"]:::external
    end

    UA -->|"calls_API:Initialization&Configuration"| API
    API -->|"invokes"| BM
    BM -->|"initiates_login&DOM_interaction"| WA
    WA -->|"returns_session_status"| BM
    BM -->|"manages_events"| EM
    EM -->|"emits_events:(message,error,end)"| UA

    click BM "https://github.com/sohunn/whatsbulk/blob/master/src/BulkMessenger.ts"
    click API "https://github.com/sohunn/whatsbulk/blob/master/src/index.ts"
    click TD "https://github.com/sohunn/whatsbulk/blob/master/src/types.ts"

    classDef user fill:#ffd1dc,stroke:#e60073,stroke-width:2px;
    classDef library fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef external fill:#d4edda,stroke:#155724,stroke-width:2px;
```
