# gruizv/whatsappchatbotwdb architecture

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

- Interactive diagram: https://gitdiagram.com/gruizv/whatsappchatbotwdb
- Repository: https://github.com/gruizv/whatsappchatbotwdb

## Overview

##### Main Components
- FastAPI Application: Represented by files like main.py (the entry point), utils.py (chatbot logic and message handling), models.py (database schema), and database.py (database connection and operations).
- PostgreSQL Database: Serves as the persistent store for conversation logs and session tracking.
- External Services: Twilio API (for sending/receiving WhatsApp messages) and ngrok (used to expose the local server to the internet for webhook callbacks).
- Supporting Layers: Environment and configuration (via .env and configuration in requirements.txt), and Tests (located in the Tests folder for chatbot logic).

##### Relationships and Dataflows
- Incoming WhatsApp messages are first received by Twilio, which is configured (using a webhook) to forward messages to the FastAPI endpoint (in main.py).
- The FastAPI application processes the incoming requests, leveraging utility functions (in utils.py) that implement the guided conversation logic.
- Interaction with the PostgreSQL database happens through operations coded in database.py using the schema defined in models.py.
- Outgoing responses, including those with emojis and contextual guidance, are sent back through Twilio to the user.
- The ngrok service is used to expose the local FastAPI server so that Twilio can reach your webhook endpoint.

##### Architectural Patterns & Technologies
- Separation of Concerns: The project separates the web server, utility logic, and database management into distinct modules.
- Service Integration: FastAPI acts as the central orchestrator that mediates between Twilio (external messaging service) and the PostgreSQL backend.
- Dependency Injection & Configuration: Usage of environment variables (with a configuration file like .env) to decouple sensitive configuration such as database credentials and Twilio tokens.
- Testing Component: There is a folder (Tests) dedicated to unit tests, indicating that testing is an integral part of the development process.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    TW("Twilio API"):::external
    NG("ngrok"):::external
    PG("PostgreSQL Database"):::database
    TESTS("Unit Tests"):::tests

    %% FastAPI Application Subgraph
    subgraph "FastAPI Application"
        subgraph "API Endpoints & Logic"
            MAIN("main.py"):::appLogic
            UTILS("utils.py"):::appLogic
        end
        subgraph "Data Access Layer"
            MODELS("models.py"):::dbAccess
            DB("database.py"):::dbAccess
        end
    end

    %% Data Flow Connections
    TW -->|"webhook"| NG
    NG -->|"exposes"| MAIN
    MAIN -->|"processes"| UTILS
    UTILS -->|"DB_operations"| DB
    DB -->|"executes queries"| PG
    MAIN -->|"sends reply"| TW
    TESTS -->|"validates"| UTILS

    %% Click Events
    click MAIN "https://github.com/gruizv/whatsappchatbotwdb/blob/main/app/main.py"
    click UTILS "https://github.com/gruizv/whatsappchatbotwdb/blob/main/app/utils.py"
    click MODELS "https://github.com/gruizv/whatsappchatbotwdb/blob/main/app/models.py"
    click DB "https://github.com/gruizv/whatsappchatbotwdb/blob/main/app/database.py"
    click TESTS "https://github.com/gruizv/whatsappchatbotwdb/blob/main/Tests/chatbot_logic_dev.py"

    %% Styles
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef appLogic fill:#AED6F1,stroke:#1A5276,stroke-width:2px;
    classDef dbAccess fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef tests fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
