# worldbank/whatsapp-rag-example architecture

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

- Interactive diagram: https://gitdiagram.com/worldbank/whatsapp-rag-example
- Repository: https://github.com/worldbank/whatsapp-rag-example

## Overview

##### Project type and purpose
- This is a backend-centric RAG (Retrieval-Augmented Generation) Chatbot application.
- Users interact via WhatsApp (Twilio WhatsApp Messaging API).
- Under the hood it uses FastAPI to expose endpoints, LangChain to build LLM chains, a vector store for document retrieval, and PostgreSQL for conversation logging.

##### File structure
- Top-level scripts:
- main.py – FastAPI application and Twilio webhook handler
- basic_chain.py, rag_chain.py, ensemble.py – LangChain chains / prompt logic
- local_loader.py, remote_loader.py – document ingestion pipelines
- splitter.py – document chunking
- vector_store.py – embedding and vector-DB management
- memory.py – session/memory management
- models.py – SQLAlchemy ORM definitions for Postgres logging
- utils.py – shared helpers
- Folders:
- data/ – WHO PDF documents used as knowledge base
- examples/ – sample files for testing
- Config and dependencies: requirements.txt, .env (credentials), .gitignore.

##### README for additional insights
- External services: OpenAI API or HuggingFace LLMs; Twilio WhatsApp; PostgreSQL; Ngrok for local tunneling.
- Workflow steps: document loading → splitting → vector DB creation → memory setup → LLM chain creation → API exposure → Twilio integration.

##### Main components and interactions
a. Components
- WhatsApp User (Client)
- Twilio WhatsApp API (Webhook + Messaging service)
- FastAPI Server (main.py)
- Document Ingestion Pipeline
– Loader modules (local_loader.py, remote_loader.py)
– Splitter (splitter.py)
– Embedding & Vector Store (vector_store.py + store files)
- Memory Manager (memory.py)
- LLM Chains (basic_chain.py, rag_chain.py, ensemble.py)
- External LLM Services (OpenAI / HuggingFace API)
- PostgreSQL Database (models.py via SQLAlchemy)
b. Relationships & data flow
1. WhatsApp User → (WhatsApp message) → Twilio API → POST to FastAPI webhook
2. FastAPI receives message → consult Memory Manager (memory.py) → query Vector Store → retrieve context chunks
3. FastAPI → invoke LLM Chain → call external LLM API → generate response
4. FastAPI → log conversation to PostgreSQL via models.py → send reply back through Twilio API → WhatsApp User
5. (Offline/infrequent) Document Ingestion Pipeline: read PDFs from data/, split, embed, populate Vector Store
c. Architectural patterns & principles
- Layered architecture: API layer, application logic (chains + memory), data layer (vector DB + SQL DB)
- Pipeline pattern for document ingestion
- Adapter pattern for external services (Twilio, OpenAI/HuggingFace)
- Single-responsibility per module (loader vs. chain vs. memory vs. utils)
d. Key technologies & libraries
- FastAPI, Uvicorn
- LangChain, OpenAI / HuggingFace client
- Chroma/hnswlib vector store
- SQLAlchemy + psycopg2 (PostgreSQL)
- Twilio Python SDK
- Ngrok for dev tunnel
- Python PDF readers (in local_loader.py)

##### Essential elements to capture
- Separation of concerns: ingestion vs. query vs. logging
- Data flow from WhatsApp → Twilio → FastAPI → LLM → WhatsApp
- Asynchronous or synchronous calls (e.g., external LLM API)
- Persistent storage: vector DB for retrieval, SQL DB for logs
- Configuration boundary (.env variables, credentials)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services"
        direction TB
        WhatsAppUser["WhatsApp User"]:::external
        TwilioAPI["Twilio WhatsApp API"]:::external
        LLMAPI["OpenAI/HuggingFace LLM API"]:::external
        PostgresDB["PostgreSQL Database"]:::datastore
    end

    %% Application Layer
    subgraph "Backend Application" 
        direction TB
        FastAPI["FastAPI Server\n(main.py)"]:::backend
        Memory["Memory Manager\n(memory.py)"]:::backend
        subgraph "LLM Chains"
            direction TB
            BasicChain["Basic Chain\n(basic_chain.py)"]:::backend
            RAGChain["RAG Chain\n(rag_chain.py)"]:::backend
            EnsembleChain["Ensemble Chain\n(ensemble.py)"]:::backend
        end
        Models["ORM Models\n(models.py)"]:::backend
        Utils["Shared Helpers\n(utils.py)"]:::backend
    end

    %% Document Ingestion Pipeline
    subgraph "Document Ingestion Pipeline"
        direction TB
        DataFolder["Knowledge Base Documents\n(data/)"]:::datastore
        LocalLoader["Local Loader\n(local_loader.py)"]:::backend
        RemoteLoader["Remote Loader\n(remote_loader.py)"]:::backend
        Splitter["Document Splitter\n(splitter.py)"]:::backend
        VectorStore["Vector Store\n(vector_store.py)"]:::datastore
    end

    %% Query Workflow
    WhatsAppUser -->|"WhatsApp message"| TwilioAPI
    TwilioAPI -->|"POST /webhook"| FastAPI
    FastAPI -->|"load_memory()"| Memory
    Memory -->|"query()"| VectorStore
    VectorStore -->|"retrieved chunks"| FastAPI
    FastAPI -->|"invoke_chain()"| BasicChain
    FastAPI -->|"invoke_chain()"| RAGChain
    FastAPI -->|"invoke_chain()"| EnsembleChain
    BasicChain -->|"LLM call"| LLMAPI
    RAGChain -->|"LLM call"| LLMAPI
    EnsembleChain -->|"LLM call"| LLMAPI
    LLMAPI -->|"response"| BasicChain
    LLMAPI -->|"response"| RAGChain
    LLMAPI -->|"response"| EnsembleChain
    BasicChain --> FastAPI
    RAGChain --> FastAPI
    EnsembleChain --> FastAPI
    FastAPI -->|"log_conversation()"| Models
    Models -->|"persist"| PostgresDB
    FastAPI -->|"send_reply"| TwilioAPI
    TwilioAPI -->|"WhatsApp message"| WhatsAppUser

    %% Ingestion Workflow
    DataFolder --> LocalLoader
    DataFolder --> RemoteLoader
    LocalLoader --> Splitter
    RemoteLoader --> Splitter
    Splitter -->|"embed()"| VectorStore

    %% Click Events
    click FastAPI "https://github.com/worldbank/whatsapp-rag-example/blob/main/main.py"
    click BasicChain "https://github.com/worldbank/whatsapp-rag-example/blob/main/basic_chain.py"
    click RAGChain "https://github.com/worldbank/whatsapp-rag-example/blob/main/rag_chain.py"
    click EnsembleChain "https://github.com/worldbank/whatsapp-rag-example/blob/main/ensemble.py"
    click LocalLoader "https://github.com/worldbank/whatsapp-rag-example/blob/main/local_loader.py"
    click RemoteLoader "https://github.com/worldbank/whatsapp-rag-example/blob/main/remote_loader.py"
    click Splitter "https://github.com/worldbank/whatsapp-rag-example/blob/main/splitter.py"
    click VectorStore "https://github.com/worldbank/whatsapp-rag-example/blob/main/vector_store.py"
    click Memory "https://github.com/worldbank/whatsapp-rag-example/blob/main/memory.py"
    click Models "https://github.com/worldbank/whatsapp-rag-example/blob/main/models.py"
    click Utils "https://github.com/worldbank/whatsapp-rag-example/blob/main/utils.py"
    click DataFolder "https://github.com/worldbank/whatsapp-rag-example/tree/main/data/"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFD700,stroke:#000,stroke-width:1px
```
