# ilanbenb/wa_llm architecture

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

- Interactive diagram: https://gitdiagram.com/ilanbenb/wa_llm
- Repository: https://github.com/ilanbenb/wa_llm

## Overview

##### Main Components
- FastAPI Webhook Backend: Represented by the main entry point in app/main.py. Indicate that this component handles incoming HTTP requests (i.e., webhook calls) and serves as the service orchestrator.
- WhatsApp Web API Client: Found in src/whatsapp/client.py (and related files like init_groups.py). This acts as the interface between the bot and the WhatsApp group chats.
- Message Handling & Routing: Under src/handler, these components (including router.py and knowledge_base_answers.py) manage message processing and decide when/how the bot should respond.
- AI-based Message Processing: Although not a separate module, the bot integrates with an external AI service (the Voyage AI API) – this should be a clearly identified external dependency.
- Database: The README specifies a PostgreSQL database (with pgvector extension) along with migration files in the “migrations” directory and models under src/models. Represent the database as another distinct component.
- Daily Ingest and Summary Sync: Components for daily ingestion and summarization exist in src/daily_ingest and src/daily_summary_sync. They are likely background tasks or scheduled jobs that keep track of historical data and summary generation.
- Configuration & Setup: Consider drawing small ancillary nodes for configuration (from src/config) and dependency management (e.g., Alembic in alembic.ini and migrations).

##### Relationships and Interactions
- API Interactions: Highlight the call-out from the backend to the Voyage AI API for processing, and then back to the WhatsApp client to send the response.
- Database Communication: Connect the backend to the PostgreSQL database (including migration and model interactions), indicating read/write operations.

##### Architectural Patterns and Principles
- Separation of Concerns: Emphasize the division between the API/webhook layer, message handling logic, external API integration, and persistence/database layers.
- Modularity: Incorporate a note on how the system breaks down into discrete modules (e.g., WhatsApp client, handler, AI processing) that interact via clearly defined interfaces.
- Containerization and Deployment: Note the presence of multiple Docker Compose files (docker-compose.yml, docker-compose.local-run.yml, etc.) to support containerized deployment—implying that the system is composed of several containerized services.
- Scalability: Where appropriate, indicate that the design supports horizontal scaling (e.g., multiple instances of the FastAPI app or background ingest tasks).

##### Diagrammatic Elements
- Use clear, descriptive labels for each component (e.g., “FastAPI Webhook”, “WhatsApp Client”, “Voyage AI Integration”, “PostgreSQL Database”).
- Incoming group messages → FastAPI webhook
- Internal data routing (to message handlers and daily processing components)
- Outgoing API requests to the Voyage AI service and then back via the WhatsApp client
- Database read/write operations
- Rectangles for service components (backend, handlers)
- Optionally, use cloud containers to denote Dockerized services.
- Annotations that detail technologies/frameworks:
- Python (FastAPI, asyncpg)
- Docker & Docker Compose (deployment and orchestration)
- PostgreSQL with pgvector support (database)
- Alembic for migrations
- WhatsApp Web API integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Service
    WhatsAppExt["WhatsApp Group (External)"]:::external

    %% Core Backend
    backend["FastAPI Webhook"]:::backend

    %% Message Handling Subgraph
    subgraph "Message Handling"
        router["Router"]:::handler
        kbAnswers["Knowledge Base Answers"]:::handler
    end

    %% WhatsApp API Client
    whatsappClient["WhatsApp API Client"]:::backend

    %% External AI Integration
    voyageAi["Voyage AI Integration"]:::external

    %% Database
    postgres["PostgreSQL Database"]:::database

    %% Daily Processes Subgraph
    subgraph "Daily Processes"
        dailyIngest["Daily Ingest Process"]:::processing
        dailySummary["Daily Summary Sync Process"]:::processing
    end

    %% Configuration & Setup
    config["Configuration & Setup"]:::config

    %% Data Flow Connections
    WhatsAppExt -->|"incoming_message"| backend
    backend -->|"routes_to"| router
    backend -->|"routes_to"| kbAnswers
    backend -->|"calls_AI"| voyageAi
    voyageAi -->|"returns_response"| backend
    backend -->|"sends_message"| whatsappClient
    backend -->|"db_ops"| postgres
    dailyIngest -->|"processes_data"| postgres
    dailySummary -->|"processes_data"| postgres
    backend -->|"triggers"| dailyIngest
    backend -->|"triggers"| dailySummary
    config -->|"provides_settings"| backend
    config -->|"manages_migrations"| postgres

    %% Click Events for Component Mapping
    click backend "https://github.com/ilanbenb/wa_llm/blob/main/app/main.py"
    click whatsappClient "https://github.com/ilanbenb/wa_llm/blob/main/src/whatsapp/client.py"
    click whatsappClient "https://github.com/ilanbenb/wa_llm/blob/main/src/whatsapp/init_groups.py"
    click router "https://github.com/ilanbenb/wa_llm/blob/main/src/handler/router.py"
    click kbAnswers "https://github.com/ilanbenb/wa_llm/blob/main/src/handler/knowledge_base_answers.py"
    click postgres "https://github.com/ilanbenb/wa_llm/tree/main/src/models"
    click postgres "https://github.com/ilanbenb/wa_llm/tree/main/migrations"
    click dailyIngest "https://github.com/ilanbenb/wa_llm/blob/main/src/daily_ingest/daily_ingest.py"
    click dailySummary "https://github.com/ilanbenb/wa_llm/tree/main/src/daily_summary_sync"
    click config "https://github.com/ilanbenb/wa_llm/tree/main/src/config"
    click config "https://github.com/ilanbenb/wa_llm/blob/main/alembic.ini"

    %% Styles
    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef handler fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef database fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef processing fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
```
