How san99tiago/aws-whatsapp-chatbot works
Project Type and Purpose
• This is a serverless, event-driven chatbot application that integrates WhatsApp Business APIs with AWS services.
• Purpose: act as a personal assistant using Generative AI (via Amazon Bedrock) and private data (Events/Contacts/TODOs/etc.) stored in DynamoDB and surfaced through RAG (Retrieval-Augmented Generation) on an OpenSearch Serverless vector DB.
File Structure
Top-level directories & their roles:
• cdk/ → AWS CDK constructs and stacks (infrastructure-as-code)
• backend/
– whatsapp_webhook/ → API Gateway Lambda handlers for incoming WhatsApp events
– trigger/ → code that invokes or schedules the Step Function
– state_machine/ → AWS Step Functions handler plus integration and processing tasks
– bedrock_agent/ → custom Lambda to wrap calls to Amazon Bedrock + DynamoDB helpers
– common/ → shared models, helpers (DynamoDB, Secrets Manager), logging
• lambda-layers/ → shared dependencies packaged as Lambda Layers
• assets/ → architecture slides & Excalidraw drafts
• docs/ → manual setup steps (Meta and AWS configuration)
Extract Key Architectural Insights from the README
• Core compute: AWS Lambda (handlers, Bedrock agent, trigger code)
• Orchestration: AWS Step Functions state machine with branches for text, voice, RAG, live data calls
• Generative AI: Amazon Bedrock agents calling LLMs + on-the-fly API/database queries
• Vector search: OpenSearch Serverless for PDF-based knowledge base
• Data store: Amazon DynamoDB for personal data (Contacts, Events, TODOs, Projects)
• Infra provisioning: AWS CDK (cdk/app.py, cdk/stacks)
Main Components & Their Interactions
a. Components
1. User (WhatsApp client)
2. Meta/WhatsApp Business Cloud API
3. API Gateway → Lambda (whatsapp_webhook/api/v1/main.py)
4. “Trigger” Lambda (invokes Step Function)
5. AWS Step Functions state machine
• Choice State: text vs. voice
• Tasks: process_text, process_voice, bedrock_agent tasks, send_message
6. Amazon Bedrock Agent (Lambda)
7. OpenSearch Serverless Vector DB (RAG store)
8. Amazon DynamoDB (private data store)
9. Outbound WhatsApp message sender (via Bedrock Agent or separate Lambda)
10. CDK Stack (infrastructure layer)
b. Data Flow & Control
1. User sends message → Meta WhatsApp API
2. API Gateway triggers WhatsApp Webhook Lambda
3. Webhook Lambda parses payload & calls Step Functions StartExecution
4. Step Functions routes based on input type
• Text: RAG retrieval from OpenSearch → LLM call → optional DynamoDB calls via Bedrock Agent
• Voice: speech-to-text (if implemented) → same RAG/LLM pipeline
5. Bedrock Agent Lambda handles LLM prompts + orchestrates DynamoDB reads/writes via helper
6. Processed response flows back through Step Function → “send_message” task → calls Meta API (via secrets in Secrets Manager)
7. User receives WhatsApp reply
Architectural Patterns & Principles
• Serverless microservices: small, single-purpose Lambdas
• Orchestration over choreography: central Step Functions engine
• RAG pattern: combine vector search (OpenSearch) + LLM prompting
• Infrastructure as code: AWS CDK stacks modularized (API, State Machine, common resources)
• Layered code reuse: common helpers, models in lambda-layers