How ilanbenb/wa_llm works
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