# mautrix/whatsapp architecture

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

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

## Overview

##### Project Type and Purpose
- The README tells us that “mautrix-whatsapp” is a Matrix-WhatsApp puppeting bridge based on the whatsmeow library. It is designed to enable communication between Matrix and WhatsApp.
- The project is a full-stack service in the sense that it interfaces with two distinct systems (Matrix and WhatsApp) even though it is implemented as a Go application. It mainly functions as a middleware/bridge, managing authentication, message conversion, and synchronization.

##### File Structure
- Top-Level Components:
– The “cmd/mautrix-whatsapp” directory contains the main entry point (main.go), along with legacy migration and provisioning files, indicating the service startup and support for schema migrations.
– The “pkg” directory is the heart of the project and is subdivided into modules:
▪ pkg/connector: Contains files related to handling events, managing configurations, client connections, analytics, commands, media handling, proxy support, and integration with WhatsApp (via whatsmeow) and Matrix.
▪ pkg/msgconv: Handles message conversion between Matrix and WhatsApp formats—there are files dedicated to handling text, media, contacts, locations, polls, etc.
▪ pkg/waid: Manages WhatsApp Identification mappings and metadata.
– Configuration and deployment-related files (Dockerfile, docker-run.sh, .github workflows, build scripts) highlight that containerization, CI/CD, and deployment automation are integrated.

##### Extract Architectural Insights from the README
- The README links to detailed documentation on setup, usage, and authentication, which indicates that the system likely interacts with both Matrix homeservers and WhatsApp protocols.
- The inclusion of a roadmap suggests planned enhancements or additional functionalities, so the system must be flexible and modular for future extension.

a. Main Components:
- Entry Point: “mautrix-whatsapp” executable (from cmd/mautrix-whatsapp) which initiates the service.
- Connector Module: The pkg/connector package, which is responsible for handling real-time events, command processing, configuration, communication with Matrix and WhatsApp endpoints, analytics, and database-backed features like backfilling and migration.
- Message Conversion Module: The pkg/msgconv package, which translates messages between Matrix and WhatsApp formats.
- WAID Module: The pkg/waid package, managing WhatsApp user IDs and associated metadata.
- External Services:
- Matrix Homeserver – for receiving and sending Matrix events.
- WhatsApp service (utilizing whatsmeow) – for managing WhatsApp sessions and message exchanges.
- Deployment/Infrastructure: Containerization (via Docker) and CI/CD pipelines (GitHub workflows, GitLab CI).

b. Relationships & Data Flow:
- Data flows from Matrix events into the Connector, which then communicates with the Message Conversion module when a format change is needed.
- Converted messages are forwarded to WhatsApp via the Connector, using the whatsmeow integration.
- Similarly, incoming messages from WhatsApp go through the WAID module for appropriate mapping and then are converted and relayed to Matrix.
- Configuration, command handling, and analytics also flow through the Connector to maintain state and perform background tasks (e.g., backfill, migrations).

c. Architectural Patterns & Principles:
- Modular Design: Each functionality (connector, message conversion, WAID management) is neatly separated, supporting maintainability and extensibility.
- Bridge/Adapter Pattern: The system acts as an intermediary translating protocols between Matrix and WhatsApp.
- Containerized Deployment: The Dockerfile and deployment scripts indicate that the service is packaged with isolation in mind.

d. Relevant Technologies:
- Go programming language for core implementation.
- Whatsmeow for WhatsApp integration.
- Docker for containerization.
- CI/CD tools (GitHub workflows, GitLab CI) for automated testing and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    A("Matrix Homeserver"):::external
    B("WhatsApp Service (whatsmeow)"):::external

    %% Core Bridge Components
    subgraph "Core Bridge"
        EP("Entry Point"):::internal
        CT("Connector Module"):::internal
        MC("Message Conversion Module"):::internal
        WA("WAID Module"):::internal
    end

    %% Deployment and Infrastructure
    subgraph "Deployment Infrastructure"
        D("Docker Container"):::infra
        C("CI/CD Pipelines"):::infra
    end

    %% Data Flow: Outbound from Matrix to WhatsApp
    A -->|"MatrixEvents"| CT
    EP -->|"initiate"| CT
    CT -->|"ConversionRequest"| MC
    MC -->|"ConvertedMessage"| CT
    CT -->|"ForwardToWhatsApp"| B

    %% Data Flow: Inbound from WhatsApp to Matrix
    B -->|"IncomingMessage"| WA
    WA -->|"IDMapping"| CT
    CT -->|"RelayToMatrix"| A

    %% Infrastructure Support
    D ---|"DockerSupports"| EP
    C ---|"CICDSupports"| EP

    %% Click Events for Components
    click EP "https://github.com/mautrix/whatsapp/blob/main/cmd/mautrix-whatsapp/main.go"
    click CT "https://github.com/mautrix/whatsapp/blob/main/pkg/connector/connector.go"
    click MC "https://github.com/mautrix/whatsapp/blob/main/pkg/msgconv/msgconv.go"
    click WA "https://github.com/mautrix/whatsapp/blob/main/pkg/waid/id.go"

    %% Styles
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef internal fill:#88ccff,stroke:#333,stroke-width:2px;
    classDef infra fill:#d3f8d3,stroke:#333,stroke-width:2px;
```
