# secreto31126/whatsapp-api-js architecture

> Architecture diagram of the GitHub repository secreto31126/whatsapp-api-js, 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/secreto31126/whatsapp-api-js
- Repository: https://github.com/secreto31126/whatsapp-api-js

## Overview

This project is a TypeScript framework designed to work as a server-agnostic implementation of WhatsApp’s official API. Its main purpose is to let developers easily integrate WhatsApp messaging features into a variety of server environments (e.g., Express, Next, Node HTTP, Bun, Deno, SvelteKit, Vercel, etc.) with full TypeScript support and built-in middleware.

##### Main Components
- WhatsApp API Core: The central “WhatsAppAPI” class (located in src/index.ts) is the heart of the framework. It handles initialization, configuration (tokens, secrets, webhook verification), and holds event emitters for incoming (on.message) and outgoing (on.sent) messages.
- Message Definitions: Found in src/messages (e.g., contacts.ts, globals.ts, interactive.ts, etc.), these define the different types of messages that can be sent/received.
- Middleware Adapters: The src/middleware directory contains adapters for various server runtimes/frameworks (e.g., express, adonis, bun, deno, next, node-http, sveltekit, vercel, web-standard). These modules provide integration points enabling the library to be used in different environments.
- Environment/Setup Files: The src/setup directory (e.g., node.ts, bun.ts, deno.ts, web.ts) provides tailored initialization routines for different platforms.
- Utility and Core Helpers: Modules like src/emitters.ts, src/errors.ts, and src/utils.ts encapsulate common functionality such as error handling and event emission.
- Standalone Functionality: The src/standalone.ts file may provide a way to run or test the library independent of server integration.
- Testing: The test directory contains modules for unit tests and mocks ensuring the integrity of message handling and integration.

##### Establish Relationships and Data Flow
- Client Integration: At the top, external client code (user implementations) will import and initialize the WhatsAppAPI class, providing configuration parameters and setting event handlers.
- Incoming Requests & Webhook Handling: Webhook events from the Meta WhatsApp Cloud API are received by the server. They are processed by middleware adapter(s) to properly pass parsed request data into the API logic.
- Message Processing and Event Emission: Once a message is received, it is parsed and routed through the core API, leveraging message type definitions and error handling. Then, events (such as ‘on.message’ and ‘on.sent’) are triggered.
- Outgoing Messaging: Responses or outgoing messages are built using one of the message constructors found in src/messages, sent via the framework’s reply logic.
- Environmental Adaptation: The setup modules adjust the library’s behavior based on the runtime environment (e.g., initializing for Node, Bun, Deno, or web-based deployments).
- Integration Testing: The tests ensure that these components interact as expected, covering both API logic and middleware integration.

##### Architectural Patterns
- Modular and Pluggable Architecture: Separation into distinct directories for messages, middleware, and setups allows for modular extension and easy integration with various runtimes.
- Event-Driven Design: The “on” event handlers (for message receipt and sending) indicate a decoupled, event-driven approach.
- Abstraction Layer for Runtimes: Middleware adapters hide the differences between various server frameworks, making the library server agnostic.

##### Incorporate Relevant Technologies and Frameworks
- TypeScript for type safety.
- Multiple middleware patterns for popular server frameworks (Express, Next, etc.).
- Standard Node.js modules (and environment-specific modules for Bun, Deno) with configuration through Firebase (firebase.json) and CI/CD setups (GitHub workflows for releases, code analysis, and deploys).

##### Essential Elements
- Use clear labels for each component.
- From the external WhatsApp cloud API to the Webhook (middleware adapters).
- From the middleware to the core API handler and then back out.
- Core Business Logic (e.g., WhatsAppAPI class, event handlers).
- Middleware Adapters (each tailored for a different runtime).
- Supporting Modules (messages, setup, utilities).
- External Systems (Meta WhatsApp API, client code).
- Optionally, include CI/CD and testing modules (from .github and test directories) as supporting but peripheral aspects.

##### Detailed Steps for the Engineer
- An “Environment Setup” block that connects to the API core, indicating how runtime-specific initialization is performed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    External["External Client Code"]:::external
    WhatsAppCloud["Meta WhatsApp Cloud API"]:::external

    %% Middleware Adapters Subgraph
    subgraph "Middleware Adapters"
        Express["Express Adapter"]:::middleware
        Next["Next Adapter"]:::middleware
        Adonis["Adonis Adapter"]:::middleware
        BunAdapter["Bun Adapter"]:::middleware
        DenoAdapter["Deno Adapter"]:::middleware
        NodeHTTP["Node HTTP Adapter"]:::middleware
        SvelteKit["SvelteKit Adapter"]:::middleware
        Vercel["Vercel Adapter"]:::middleware
        WebStandard["Web-Standard Adapter"]:::middleware
    end

    %% Core API
    API["WhatsAppAPI Core"]:::core

    %% Downstream Components
    MT["Message Types"]:::module

    subgraph "Environment Setup"
        NodeSetup["Node Setup"]:::setup
        BunSetup["Bun Setup"]:::setup
        DenoSetup["Deno Setup"]:::setup
        WebSetup["Web Setup"]:::setup
    end

    subgraph "Utility & Core Helpers"
        Emitters["Emitters"]:::utility
        Errors["Errors"]:::utility
        UtilsFile["Utils"]:::utility
    end

    Standalone["Standalone Functionality"]:::standalone
    Test["Testing Suite"]:::test

    %% Data Flow Connections (Vertical Layout)
    External -->|"initializes"| API
    WhatsAppCloud -->|"webhook-request"| Express
    WhatsAppCloud -->|"webhook-request"| Next
    WhatsAppCloud -->|"webhook-request"| Adonis
    WhatsAppCloud -->|"webhook-request"| BunAdapter
    WhatsAppCloud -->|"webhook-request"| DenoAdapter
    WhatsAppCloud -->|"webhook-request"| NodeHTTP
    WhatsAppCloud -->|"webhook-request"| SvelteKit
    WhatsAppCloud -->|"webhook-request"| Vercel
    WhatsAppCloud -->|"webhook-request"| WebStandard

    Express -->|"forwards"| API
    Next -->|"forwards"| API
    Adonis -->|"forwards"| API
    BunAdapter -->|"forwards"| API
    DenoAdapter -->|"forwards"| API
    NodeHTTP -->|"forwards"| API
    SvelteKit -->|"forwards"| API
    Vercel -->|"forwards"| API
    WebStandard -->|"forwards"| API

    API -->|"processes"| MT
    API -->|"configures"| NodeSetup
    API -->|"configures"| BunSetup
    API -->|"configures"| DenoSetup
    API -->|"configures"| WebSetup
    API -->|"handlesErrors"| Emitters
    API -->|"handlesErrors"| Errors
    API -->|"handlesErrors"| UtilsFile
    API -->|"standaloneMode"| Standalone
    Test -->|"validates"| API

    %% Styles
    classDef external fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#cfc,stroke:#333,stroke-width:2px;
    classDef middleware fill:#fcf,stroke:#333,stroke-width:2px;
    classDef setup fill:#cff,stroke:#333,stroke-width:2px;
    classDef utility fill:#ffd,stroke:#333,stroke-width:2px;
    classDef standalone fill:#fdd,stroke:#333,stroke-width:2px;
    classDef test fill:#dfd,stroke:#333,stroke-width:2px;

    %% Click Events
    click API "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/index.ts"
    click MT "https://github.com/secreto31126/whatsapp-api-js/tree/main/src/messages"
    click Express "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/express.ts"
    click Next "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/next.ts"
    click Adonis "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/adonis.ts"
    click BunAdapter "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/bun.ts"
    click DenoAdapter "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/deno.ts"
    click NodeHTTP "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/node-http.ts"
    click SvelteKit "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/sveltekit.ts"
    click Vercel "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/vercel.ts"
    click WebStandard "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/middleware/web-standard.ts"
    click NodeSetup "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/setup/node.ts"
    click BunSetup "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/setup/bun.ts"
    click DenoSetup "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/setup/deno.ts"
    click WebSetup "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/setup/web.ts"
    click Emitters "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/emitters.ts"
    click Errors "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/errors.ts"
    click UtilsFile "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/utils.ts"
    click Standalone "https://github.com/secreto31126/whatsapp-api-js/blob/main/src/standalone.ts"
    click Test "https://github.com/secreto31126/whatsapp-api-js/tree/main/test"
```
