# cfranco92/chat-bot-openai-whatsapp architecture

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

- Interactive diagram: https://gitdiagram.com/cfranco92/chat-bot-openai-whatsapp
- Repository: https://github.com/cfranco92/chat-bot-openai-whatsapp

## Overview

##### Project Type and Purpose
- This is a full-stack Node.js application that serves as a WhatsApp chatbot. It integrates with the WhatsApp Business API to receive messages, uses OpenAI’s API for intelligent responses, and stores data in Google Sheets. It’s designed around a flexible conversation flow (appointment scheduling by default) with multi-language support.

##### File Structure
- The top-level directories and core files (app.js, routes, controllers, services) indicate the use of the Model-View-Controller (MVC)-like pattern, although this is mostly a service-based design.
- The “src/config” handles environment and configuration variables which are important for controlling the system’s behavior.
- In “src/controllers” you see webhookController.js, which suggests that incoming HTTP requests (webhooks) are immediately routed here.
- “src/routes” (webhookRoutes.js) is the Express router layer mapping endpoints to controllers.
- “src/services” contains the business logic components such as messageHandler.js, whatsappService.js, googleSheetsService.js, and openAiService.js. This is where external integrations and heavy lifting occur.
- “src/i18n” contains all internationalization assets, allowing support for multiple languages.
- The tests in “src/__tests__” confirm that the project validates its components via unit and integration testing.

##### Elements
a. Main Components:
- Client / External Systems: WhatsApp Business API is the provider of incoming messages and data, and external systems (Google Sheets API, OpenAI API) are also integral.
- HTTP Webhook Endpoint: Represented by the Express router (webhookRoutes.js) that handles inbound HTTP requests (GET for verification, POST for messages).
- Controller Layer: The webhookController.js handles routing logic and initiates service calls.
- Service Layer:
- Message Handler: Coordinates conversation flow.
- WhatsApp Service: Manages sending/receiving messages through WhatsApp.
- OpenAI Service: Processes natural language for responses.
- Google Sheets Service: Handles storing and retrieving data.
- Configuration / Environment: The config folder (with env.js) and environment variables (.env file) ensure correct API keys, tokens, and settings.
- Internationalization (i18n): Handles language-specific responses, using locales like English and Spanish.

b. Relationships and Interactions:
- The WhatsApp Business API sends webhooks to the Express server.
- The webhookRoutes maps incoming requests to webhookController.
- The controller calls the messageHandler, which orchestrates the overall process.
- Depending on the message content, the messageHandler interacts with:
- WhatsApp Service (for replies)
- OpenAI Service (for intelligent, AI-driven responses)
- Google Sheets Service (to log appointments or conversation data)
- The i18n module is used throughout to adapt responses to the user’s language based on configuration.
- Environment config is used across all components for consistent settings such as tokens, API keys, and language preferences.

c. Architectural Patterns and Design Principles:
- Separation of concerns with explicit routing, controllers, and services.
- External API integration pattern - each external service (WhatsApp, OpenAI, Google Sheets) is encapsulated within its own service module.
- Internationalization is modularized via the i18n directory.
- Configuration via environment variables increases flexibility and deployment agility.

d. Technologies and Frameworks:
- Express.js for HTTP server and routing.
- Node.js as the platform.
- Jest and Supertest for testing.
- dotenv for configuration management.
- i18next for internationalization.

##### Elements to Integrate
- Use clear labels for each component (i.e., “Webhook Routes”, “Webhook Controller”, “Message Handler”, “WhatsApp Service”, “OpenAI Service”, “Google Sheets Service”, “Internationalization Module”, “Configuration”).
- From “WhatsApp Business API” to “Webhook Routes” (incoming HTTP requests).
- From “Webhook Routes” to “Webhook Controller”, then to “Message Handler”.
- From “Message Handler” to each service (WhatsApp Service, OpenAI Service, Google Sheets Service).
- Internal server components vs external services.
- Utility modules such as configuration and i18n.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Component
    WBAPI["WhatsApp Business API"]:::external

    %% Internal Server Components
    subgraph "Internal Server"
        %% Routing Layer
        subgraph "Routing Layer"
            WR["Webhook Routes"]:::internal
        end
        %% Controller Layer
        subgraph "Controller Layer"
            WC["Webhook Controller"]:::internal
        end
        %% Service Layer
        subgraph "Service Layer"
            MH["Message Handler"]:::service
            subgraph "Service Components"
                WS["WhatsApp Service"]:::service
                STW["Send to WhatsApp"]:::service
                OA["OpenAI Service"]:::service
                GS["Google Sheets Service"]:::service
            end
        end
    end

    %% Utility Modules
    subgraph "Utility Modules"
        CF["Configuration"]:::utility
        ENV["Environment File"]:::utility
        I18n["Internationalization Module"]:::utility
    end

    %% Data Flow Connections
    WBAPI -->|"calls"| WR
    WR -->|"routes"| WC
    WC -->|"handles"| MH
    MH -->|"uses"| WS
    MH -->|"calls"| OA
    MH -->|"logs_data"| GS
    WS -->|"HTTP_call"| STW

    %% Utility Interactions
    CF -->|"provides"| MH
    ENV -->|"provides"| MH
    I18n -->|"supports"| MH

    %% Click Events
    click WR "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/routes/webhookRoutes.js"
    click WC "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/controllers/webhookController.js"
    click MH "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/services/messageHandler.js"
    click WS "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/services/whatsappService.js"
    click STW "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/services/httpRequest/sendToWhatsApp.js"
    click OA "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/services/openAiService.js"
    click GS "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/services/googleSheetsService.js"
    click CF "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/src/config/env.js"
    click ENV "https://github.com/cfranco92/chat-bot-openai-whatsapp/blob/main/.env-example"
    click I18n "https://github.com/cfranco92/chat-bot-openai-whatsapp/tree/main/src/i18n"

    %% Class Definitions for Styling
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef internal fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef service fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;
    classDef utility fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
```
