# shreyasj14/whatsapp-bulkmsg architecture

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

- Interactive diagram: https://gitdiagram.com/shreyasj14/whatsapp-bulkmsg
- Repository: https://github.com/shreyasj14/whatsapp-bulkmsg

## Overview

##### Project type and purpose
- This is an open-source “integration tool” comprising two cooperating services:
a. A Go-based “WhatsApp Bridge” that connects your personal WhatsApp account (via the Whatsmeow library) to a local SQLite store.
b. A Python “MCP Server” that implements the Model Context Protocol, exposing tools that let an LLM (Claude or Cursor) interact with your WhatsApp data and send messages.
- Use case: Allow an LLM to search messages, list chats/contacts, and send WhatsApp messages under your control.

##### File structure
- Top-level:
- whatsapp-bridge/  ← Go module
- whatsapp-mcp-server/  ← Python MCP server
- sample_numbers.xlsx  ← demo data
- whatsapp-bridge/
- main.go → entrypoint that authenticates via QR, maintains WebSocket to WhatsApp Web API, and syncs messages to SQLite.
- go.mod/go.sum → Go dependency management.
- whatsapp-mcp-server/
- main.py → Python UV-managed CLI that launches an HTTP/gRPC/MCP-compatible server.
- whatsapp.py → library module that wraps database queries and bridge RPC calls.
- send_bulk_whatsapp.py, create_sample_excel.py → utility scripts.
- pyproject.toml, uv.lock → Python dependencies via UV.
- SQLite DB files live under whatsapp-bridge/store/, and the Python server may read from them directly or via the bridge.

##### README insights
- Two main components (Go bridge + Python MCP server) are already described.
- Data flow summary:
1. Claude → Python MCP server
2. Python MCP server ↔ Go bridge or SQLite
3. Go bridge ↔ WhatsApp Web API → local SQLite
4. Responses flow back → Claude
- Key technologies: Go, Python3 (UV), SQLite, Whatsmeow, MCP.

a. Main components
- External Entities:
- WhatsApp Web API (via Whatsmeow)
- LLM Client (Claude Desktop or Cursor)
- Services:
- WhatsApp Bridge (Go)
- MCP Server (Python)
- Data Store:
- SQLite database
b. Relationships & Data Flows
c. Architectural patterns and principles
- Separation of concerns: Bridge handles protocol details and persistence; MCP server exposes a uniform toolset to the LLM.
- Microservice-style communication: Independent Go and Python processes connected via light RPC or shared DB.
- Data indexing and caching: SQLite stores and indexes chats/messages for efficient queries.
d. Key technologies/frameworks
- Go + whatsmeow for WhatsApp integration
- SQLite for local persistence
- Python + UV for MCP server
- MCP (Model Context Protocol) standard for LLM tool integration
- LLM clients: Claude Desktop, Cursor

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Entities"
        LLM["LLM Client (Claude/Cursor)"]:::external
        WAAPI["WhatsApp Web API"]:::external
    end

    subgraph "Services"
        subgraph "Go WhatsApp Bridge"
            Bridge["WhatsApp Bridge"]:::go
            QR["QR Authentication"]:::go
            GoMod["go.mod"]:::go
            GoSum["go.sum"]:::go
        end

        subgraph "Python MCP Server"
            MCP["Python MCP Server"]:::python
            MainPy["main.py"]:::python
            Wrapper["whatsapp.py"]:::python
            BulkScript["send_bulk_whatsapp.py"]:::python
            SampleGen["create_sample_excel.py"]:::python
            PyProj["pyproject.toml"]:::python
            UVLock["uv.lock"]:::python

            subgraph "MCP Tools"
                T1["search_contacts"]:::python
                T2["list_messages"]:::python
                T3["send_message"]:::python
            end
        end
    end

    DB["SQLite DB"]:::db
    SampleRoot["sample_numbers.xlsx (root)"]:::external
    SampleMCP["sample_numbers.xlsx"]:::python

    LLM -->|"MCP request"| MCP
    MCP -->|"list_messages / search_contacts"| DB
    MCP -->|"send_message RPC"| Bridge
    Bridge -->|"sync messages"| DB
    Bridge -->|"WebSocket connection"| WAAPI
    Bridge -->|"send via API"| WAAPI
    MCP -->|"invoke"| T1
    MCP -->|"invoke"| T2
    MCP -->|"invoke"| T3

    %% Click Events
    click Bridge "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-bridge/main.go"
    click GoMod "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-bridge/go.mod"
    click GoSum "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-bridge/go.sum"
    click MainPy "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/main.py"
    click Wrapper "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/whatsapp.py"
    click BulkScript "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/send_bulk_whatsapp.py"
    click SampleGen "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/create_sample_excel.py"
    click PyProj "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/pyproject.toml"
    click UVLock "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/uv.lock"
    click SampleRoot "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/sample_numbers.xlsx"
    click SampleMCP "https://github.com/shreyasj14/whatsapp-bulkmsg/blob/main/whatsapp-mcp-server/sample_numbers.xlsx"

    classDef external fill:#eeeeee,stroke:#888,stroke-dasharray: 5 5
    classDef go fill:#CFE2F3,stroke:#0366d6
    classDef python fill:#D9EAD3,stroke:#38761d
    classDef db fill:#F9E79F,stroke:#b7950b
```
