# dahshury/python-whatsapp-bot architecture

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

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

## Overview

##### Project type and purpose
- This project is a full-stack application featuring a WhatsApp bot that uses FastAPI as the backend, integrating AI services (OpenAI and Anthropic) for natural language processing.
- It also includes a Streamlit-based frontend for managing reservations and viewing conversation details stored in an SQLite database.
- Additional automated scripts handle functions such as sending reminders and backing up the database.

##### File structure to identify main components
- Backend Application (FastAPI):
- Entry point is run.py, which starts the FastAPI server.
- app/ directory holds the core code.
▪ app/config.py (configuration settings from environment variables)
▪ app/db.py (SQLite database connections and schema definitions)
▪ app/views.py (defines FastAPI routes including the webhook endpoint for WhatsApp)
- Decorators inside app/decorators provide safety and security (e.g., signature verification for incoming webhook requests).
- Services in app/services handle business logic:
▪ openai_service.py – integrates OpenAI for processing WhatsApp messages.
▪ anthropic_service.py – integrates with Anthropic.
▪ assistant_functions.py – manages reservation operations (create, update, cancel).
- Utility modules in app/utils (e.g., logging, thread management, WhatsApp-specific functions).

- Frontend Components:
- Streamlit application (st_app.py) serves as the primary UI for managing reservations.
- The app/frontend directory contains UI assets, including HTML, CSS, and JavaScript for custom widgets like a clock and a datepicker.

- External Integrations:
- WhatsApp API (via Meta developer account) for messaging.
- AI services (OpenAI and Anthropic) for intelligent response generation.
- SQLite for persistent data storage.

- Additional Scripts & Infrastructure:
- send_reminders.py – script to send automated reservation reminders.
- sqlite_backup.sh – Bash script to perform periodic backup of the SQLite database.
- CI/CD configuration found under .github/workflows and a Procfile for deployment.

a. FastAPI Backend:
- Component: API Server
- Sub-components: Webhook Endpoint (views.py), Security & Verification (decorators/security.py), Database interactions (db.py), and AI Service integration (services/*).
▪ WhatsApp API (incoming requests and outgoing responses),
▪ AI services (OpenAI & Anthropic),
▪ SQLite database.

b. Database:
- Link between the backend’s business logic (assistant_functions.py) and the database.

c. Frontend (Streamlit App):
- Component: Frontend UI
- That the Streamlit app (st_app.py) interacts with the backend for viewing and CRUD operations on reservations.
- Custom UI widgets (clock and datepicker) under app/frontend, ensuring to note the authentication aspects (from app/frontend/__init__.py using streamlit_authenticator).

d. Automated Tasks:
- Component: Reminder Service (send_reminders.py)
- Component: Database Backup Service (sqlite_backup.sh)
- How these scripts periodically connect to the database and/or WhatsApp API as needed.

e. External Integrations:

##### Architectural Patterns and Design Principles
- Clearly separate the concerns:
- Frontend vs. Backend separation.
- Service layer (business logic) decoupled from route handlers.
- Security and verification via decorators.
- If applicable, show the periodic/scheduled nature of the reminder and backup scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% FastAPI Backend Subgraph
    subgraph "FastAPI Backend"
        A1["API Server (run.py)"]
        A2["Configuration (app/config.py)"]
        A3["Database (app/db.py)"]
        A4["Views (app/views.py)"]
        subgraph "Decorators"
            D1["Security (app/decorators/security.py)"]
            D2["Safety (app/decorators/safety.py)"]
        end
        subgraph "Services"
            S1["OpenAI Service (app/services/openai_service.py)"]
            S2["Anthropic Service (app/services/anthropic_service.py)"]
            S3["Reservation Logic (app/services/assistant_functions.py)"]
        end
        U1["WhatsApp Utils (app/utils/whatsapp_utils.py)"]
    end

    %% External Integrations
    E1["WhatsApp API"]
    E2["OpenAI"]
    E3["Anthropic"]
    DB1["SQLite Database"]

    %% Frontend Subgraph
    subgraph "Frontend"
        F1["Frontend UI (st_app.py)"]
        F2["Frontend Assets (app/frontend)"]
    end

    %% Automated Tasks
    T1["Reminder Service (send_reminders.py)"]
    T2["Backup Service (sqlite_backup.sh)"]

    %% Connections within FastAPI Backend
    E1 -->|"WebhookRequest"| A4
    A4 -->|"verifySignature"| D1
    A4 -->|"verifySafety"| D2
    A4 -->|"processOpenAI"| S1
    A4 -->|"processAnthropic"| S2
    A4 -->|"manageReservation"| S3
    A4 -->|"DBQuery"| A3

    %% Connections from Services to External Integrations and Database
    S1 -->|"queryOpenAI"| E2
    S2 -->|"queryAnthropic"| E3
    S3 -->|"DBUpdate"| DB1

    %% Frontend Interaction
    F1 -->|"CRUDOps"| A4
    F1 -->|"DataFetch"| DB1

    %% Automated Tasks Interactions
    T1 -->|"sendReminder"| E1
    T1 -->|"fetchReservations"| DB1
    T2 -->|"backupDB"| DB1

    %% Class Definitions
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef database fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef scripts fill:#FFD700,stroke:#000,stroke-width:2px;

    %% Assign Classes to Nodes
    class A1,A2,A3,A4,D1,D2,S1,S2,S3,U1 backend;
    class F1,F2 frontend;
    class E1,E2,E3 external;
    class DB1 database;
    class T1,T2 scripts;

    %% Click Events
    click A1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/run.py"
    click A2 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/config.py"
    click A3 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/db.py"
    click A4 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/views.py"
    click D1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/decorators/security.py"
    click D2 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/decorators/safety.py"
    click S1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/services/openai_service.py"
    click S2 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/services/anthropic_service.py"
    click S3 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/services/assistant_functions.py"
    click U1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/app/utils/whatsapp_utils.py"
    click F1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/st_app.py"
    click F2 "https://github.com/dahshury/python-whatsapp-bot/tree/main/app/frontend"
    click T1 "https://github.com/dahshury/python-whatsapp-bot/blob/main/send_reminders.py"
    click T2 "https://github.com/dahshury/python-whatsapp-bot/blob/main/sqlite_backup.sh"
```
