# talkdai/dialog-whatsapp architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source plugin (dialog_whatsapp) written in Python. It integrates the talkd/dialog framework with the WhatsApp Business API, simplifying inbound/outbound message flows.

##### File structure
- Top-level:
- Dockerfile, docker-compose.yml → containerize the plugin and its runtime environment
- project_config.sample.toml, pyproject.toml → project metadata, dependencies, and configuration schema
- .github/workflows/python-publish.yml → CI/CD pipeline for publishing to PyPI
- dialog_whatsapp/ directory:
- plugin.py → plugin entry point and adapter logic
- settings.py → configuration loading (env vars → internal settings)
- responses.py → default response templates and business logic
- __init__.py → package initialization

##### Insights from the README
- It describes environment variables for authenticating with WhatsApp’s API and the host address for the talkd/dialog core.

a. Main components
1. talkd/dialog Core Service (external)
2. WhatsApp Plugin (this repo)
- Plugin Adapter (plugin.py)
- Configuration Loader (settings.py)
- Response Module (responses.py)
3. WhatsApp Business API (external)
4. Runtime Environment
- Docker container(s)
- Environment Variables (.env or docker-compose)
5. CI/CD Pipeline (GitHub Actions → PyPI)

b. Relationships & Data Flow
1. Incoming Message
- WhatsApp Business API → Plugin Adapter (via webhook endpoint)
- Adapter extracts payload, passes to talkd/dialog Core API (HTTP request to API_HOST)
2. Core Processing
- talkd/dialog Core applies conversation logic → returns a structured response
3. Outgoing Message
- Plugin Adapter formats response using Response Module
- Adapter forwards formatted message to WhatsApp Business API (HTTP POST)
4. Configuration & Secrets
- Settings Loader reads WHATSAPP_API_TOKEN, VERIFY_TOKEN, ACCOUNT_NUMBER, API_HOST from environment/Docker secrets
5. CI/CD
- GitHub Actions builds the package, runs tests, and publishes to PyPI on tag push

c. Architectural patterns & principles
- Plugin-based architecture: the plugin implements a well-defined interface to the core framework.
- Single Responsibility:
- plugin.py handles HTTP endpoints and orchestration
- settings.py handles config parsing and validation
- responses.py encapsulates business logic and template management
- Containerization: isolate runtime dependencies in Docker; use docker-compose for local development

d. Key technologies
- Python 3.x, FastAPI or Flask-like adapter (implicitly via plugin.py)
- TOML for project configuration and metadata (pyproject.toml, project_config.sample.toml)
- Docker & docker-compose for environment reproducibility
- GitHub Actions for CI/CD and PyPI publishing

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        Core["talkd/dialog Core Service"]:::external
        WhatsAppAPI["WhatsApp Business API"]:::external
    end

    subgraph "WhatsApp Plugin"
        Adapter["Plugin Adapter\n(plugin.py)"]:::plugin
        Settings["Configuration Loader\n(settings.py)"]:::plugin
        Responses["Response Module\n(responses.py)"]:::plugin
        Init["Package Initialization\n(__init__.py)"]:::plugin
    end

    subgraph "Infrastructure"
        DockerfileNode["Docker Container\n(Dockerfile)"]:::infra
        Compose["Local Dev & Orchestration\n(docker-compose.yml)"]:::infra
        EnvVars["Environment & Config Schema\n(project_config.sample.toml)"]:::infra
        Metadata["Project Metadata & Dependencies\n(pyproject.toml)"]:::infra
        GitIgnore["Git Ignore Rules\n(.gitignore)"]:::infra
        DockerIgnore["Docker Ignore Rules\n(.dockerignore)"]:::infra
    end

    subgraph "CI/CD Pipeline"
        GitHubActions["GitHub Actions Pipeline\n(.github/workflows/python-publish.yml)"]:::cicd
        PyPICreds["GitHub Actions Config\n(.github/pypi.yml)"]:::cicd
        Readme["Project README & Usage Guide\n(README.md)"]:::cicd
    end

    WhatsAppAPI -->|"Webhook HTTP POST\nJSON payload"| Adapter
    Adapter -->|"HTTP Request\nJSON to API_HOST"| Core
    Core -->|"HTTP Response\nJSON"| Adapter
    Adapter -->|"HTTP POST\nJSON payload"| WhatsAppAPI

    Adapter -->|"loads config"| Settings
    Adapter -->|"formats responses"| Responses
    Adapter -->|"package init"| Init

    Settings -->|"reads env/secrets"| EnvVars

    Compose -->|"orchestrates"| DockerfileNode
    DockerfileNode -->|"runs plugin"| Adapter

    GitHubActions -->|"build/test/publish"| Metadata
    GitHubActions -->|"uses credentials"| PyPICreds
    GitHubActions -->|"documents usage"| Readme

    classDef external fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef plugin fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef infra fill:#ffe0b2,stroke:#f57c00,stroke-width:1px
    classDef cicd fill:#e0e0e0,stroke:#9e9e9e,stroke-width:1px

    click Adapter "https://github.com/talkdai/dialog-whatsapp/blob/main/dialog_whatsapp/plugin.py"
    click Settings "https://github.com/talkdai/dialog-whatsapp/blob/main/dialog_whatsapp/settings.py"
    click Responses "https://github.com/talkdai/dialog-whatsapp/blob/main/dialog_whatsapp/responses.py"
    click Init "https://github.com/talkdai/dialog-whatsapp/blob/main/dialog_whatsapp/__init__.py"
    click DockerfileNode "https://github.com/talkdai/dialog-whatsapp/tree/main/Dockerfile"
    click Compose "https://github.com/talkdai/dialog-whatsapp/blob/main/docker-compose.yml"
    click EnvVars "https://github.com/talkdai/dialog-whatsapp/blob/main/project_config.sample.toml"
    click Metadata "https://github.com/talkdai/dialog-whatsapp/blob/main/pyproject.toml"
    click GitHubActions "https://github.com/talkdai/dialog-whatsapp/blob/main/.github/workflows/python-publish.yml"
    click PyPICreds "https://github.com/talkdai/dialog-whatsapp/blob/main/.github/pypi.yml"
    click DockerIgnore "https://github.com/talkdai/dialog-whatsapp/blob/main/.dockerignore"
    click GitIgnore "https://github.com/talkdai/dialog-whatsapp/blob/main/.gitignore"
    click Readme "https://github.com/talkdai/dialog-whatsapp/blob/main/README.md"
```
