# filipporomani/whatsapp-python architecture

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

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

## Overview

##### Main Components
- Core Library Module: Represented by the “whatsapp” package, including the central files such as __init__.py, constants.py, and errors.py. This component handles configuration, shared constants, and error propagation.
- Synchronous Extensions (“ext”): Inside whatsapp/ext, we have modules (_buttons.py, _media.py, _message.py, _property.py, _send_media.py, _send_others.py, _static.py) that build the synchronous API for sending and formatting messages. This set of modules is the core interface for users who prefer blocking calls.
- Asynchronous Extensions (“async_ext”): Mirroring the “ext” folder, whatsapp/async_ext provides similar functionalities but using async/await methodologies. Represent these as a dedicated component that encapsulates async message sending, media handling, and property methods.
- Examples: The examples folder provides standalone scripts (e.g., sending_message.py, sending_image.py, etc.) that illustrate how to interact with the library. This is useful for showing typical usage scenarios and for integration testing reference.
- Testing & CI: The tests directory (with async_tests.py and tests.py) and the GitHub workflows (inside the .github directory) indicate a robust CI/CD setup aimed at maintaining code quality. These can be represented as support components that ensure stability.
- Packaging & Configuration: The pyproject.toml and various GitHub configuration files (workflows, issue templates, etc.) point out that the project has strong community and deployment support.

##### Component Relationships & Data Flows
- Client Application → Library: An external client or application code (often via one of the example scripts) will call into the wrapper’s synchronous or asynchronous interface.
- CI/CD: Illustrate that tests invoke the library’s core functionality and that CI (GitHub workflows) runs across both sync and async use cases.

##### Important Architectural Patterns & Design Principles
- Error & Exception Handling: Centralizing error handling in its own module illustrates a separation of concerns. Display how errors propagate from the functional modules to the error handler.
- External Dependency: Emphasize the integration point with the WhatsApp Cloud API as an external system. It is crucial to show that this library is essentially an abstract layer between client code and the WhatsApp Cloud API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    subgraph "Internal Components"
        CL["Core Library (whatsapp: __init__.py, constants.py, errors.py)"]:::core
        SYNC["Synchronous API (whatsapp/ext)"]:::api_sync
        ASYNC["Asynchronous API (whatsapp/async_ext)"]:::api_async
    end

    %% External Service
    subgraph "External Services"
        WA["WhatsApp Cloud API"]:::external
    end

    %% Support & Integration
    subgraph "Support & Integration"
        EX["Examples (Usage Demos)"]:::support
        TEST["Tests & CI/CD"]:::support
        PKG["Packaging & Configuration"]:::support
    end

    %% Relationships
    EX -->|"calls"| SYNC
    EX -->|"calls"| ASYNC

    SYNC -->|"sendsMessage"| WA
    ASYNC -->|"sendsMessage"| WA

    SYNC -->|"handlesError"| CL
    ASYNC -->|"handlesError"| CL

    TEST -->|"validates"| CL
    TEST -->|"validates"| SYNC
    TEST -->|"validates"| ASYNC

    PKG -->|"configures"| CL
    PKG -->|"configures"| SYNC
    PKG -->|"configures"| ASYNC
    PKG -->|"supports"| TEST

    %% Click Events
    click CL "https://github.com/filipporomani/whatsapp-python/blob/main/whatsapp/__init__.py"
    click CL "https://github.com/filipporomani/whatsapp-python/blob/main/whatsapp/constants.py"
    click CL "https://github.com/filipporomani/whatsapp-python/blob/main/whatsapp/errors.py"
    click SYNC "https://github.com/filipporomani/whatsapp-python/tree/main/whatsapp/ext"
    click ASYNC "https://github.com/filipporomani/whatsapp-python/tree/main/whatsapp/async_ext"
    click EX "https://github.com/filipporomani/whatsapp-python/tree/main/examples"
    click TEST "https://github.com/filipporomani/whatsapp-python/tree/main/tests"
    click PKG "https://github.com/filipporomani/whatsapp-python/blob/main/pyproject.toml"
    click PKG "https://github.com/filipporomani/whatsapp-python/blob/main/.github"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef api_sync fill:#A9DFBF,stroke:#28B463,stroke-width:2px;
    classDef api_async fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef support fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
```
