# meyer1994/wa architecture

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

- Interactive diagram: https://gitdiagram.com/meyer1994/wa
- Repository: https://github.com/meyer1994/wa

## Overview

##### Project type and purpose
- This is a serverless WhatsApp Bot built in Python using FastAPI (app.py, routes.py) and deployed as an AWS Lambda function (handler.py).
- It ingests incoming WhatsApp messages, persists them in DynamoDB, calls OpenAI to generate a response, persists chat records, and replies via the WhatsApp API.

##### File structure
- Top-level:
- handler.py – AWS Lambda entry point
- infra.py – CDK infra definition (ignored per instructions)
- docker-compose.yml, Dockerfile – local dev environment
- pyproject.toml – Python project config
- wa/ package:
- app.py – FastAPI application instance
- routes.py – HTTP endpoint definitions
- deps.py, config.py – dependency injection and configuration
- agents/ – business-logic modules for different bot skills (math, todos, log)
- dynamo/ – DynamoDB wrappers for events, messages, and WhatsApp raw events
- blob.py – S3 (RAG bucket) interactions
- whats/ – WhatsApp API client and models
- logs.py, lifespan.py – application logging and startup/shutdown hooks

##### README insights
- Uses AWS Lambda behind API Gateway to expose a POST webhook for WhatsApp events
- Two DynamoDB tables (EVENTS_TABLE, MESSAGES_TABLE)
- One S3 bucket for RAG artifacts
- External dependency: OpenAI API

##### Main components
a. External WhatsApp service (Meta/Twilio WhatsApp API)
b. AWS API Gateway (webhook endpoint)
c. AWS Lambda function running FastAPI (handler.py → wa/app.py)
d. DynamoDB:
- EVENTS_TABLE – raw inbound events
- MESSAGES_TABLE – chat history
e. S3 bucket – RAG storage (blob.py)
f. OpenAI API – model inference
g. Logging/Monitoring – CloudWatch (implied by AWS Lambda)

##### Relationships and data flows
- WhatsApp → API Gateway: inbound webhook POST
- API Gateway → Lambda: invoke FastAPI endpoint
- Lambda → DynamoDB (events): store raw event
- Lambda → OpenAI API: request response
- OpenAI → Lambda: return generated text
- Lambda → DynamoDB (messages): store chat message
- Lambda → WhatsApp API client: send reply
- Lambda → S3 bucket: read/write RAG artifacts (optional, when needed)

##### Architectural patterns and design principles
- Serverless single-function pattern: one Lambda hosts the FastAPI app
- Layered application structure:
- API layer (routes.py)
- Business-logic layer (agents/)
- Persistence layer (dynamo/, blob.py)
- Integration layer (whats/, OpenAI client)
- Dependency injection via deps.py for easier testing and swapping implementations

##### Detail level
- You show both DynamoDB tables separately
- OpenAI call as a distinct step
- That S3 is used for RAG artifacts (optional path)
- Do not include CDK code; represent only logical AWS services

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Services"
        WhatsApp["WhatsApp API"]:::external
        OpenAI["OpenAI API"]:::external
    end

    subgraph "AWS Cloud"
        ApiGw["API Gateway"]:::aws
        subgraph "AWS Lambda"
            Handler["handler.py"]:::compute

            subgraph "API Layer"
                App["wa/app.py"]:::compute
                Routes["wa/routes.py"]:::compute
            end

            subgraph "Business Logic"
                MainAgent["wa/agents/main.py"]:::compute
                LogAgent["wa/agents/log.py"]:::compute
                MathAgent["wa/agents/math.py"]:::compute
                TodoAgent["wa/agents/todos.py"]:::compute
            end

            subgraph "Persistence Layer"
                MessagesWrapper["wa/dynamo/messages.py"]:::compute
                EventsWrapper["wa/dynamo/tools.py"]:::compute
                WhatsappWrapper["wa/dynamo/whatsapp.py"]:::compute
                Blob["wa/blob.py"]:::compute
            end

            subgraph "Integration Layer"
                WhatsClient["wa/whats/client.py"]:::compute
                WhatsModels["wa/whats/models.py"]:::compute
            end

            Lifespan["wa/lifespan.py"]:::compute
            Logs["wa/logs.py"]:::compute
        end

        EventsDB[(EVENTS_TABLE)]:::aws
        MessagesDB[(MESSAGES_TABLE)]:::aws
        Bucket[(RAG S3 Bucket)]:::aws
        CloudWatch["CloudWatch"]:::aws
    end

    WhatsApp --> ApiGw
    ApiGw --> Handler
    Handler --> App
    App --> Lifespan
    App --> Logs
    App --> Routes

    Routes --> EventsWrapper
    Routes --> WhatsappWrapper
    Routes --> MessagesWrapper
    Routes --> Blob
    Routes --> MainAgent
    Routes --> WhatsClient

    MainAgent --> LogAgent
    MainAgent --> MathAgent
    MainAgent --> TodoAgent

    WhatsClient --> WhatsModels
    WhatsClient --> WhatsApp

    EventsWrapper --> EventsDB
    WhatsappWrapper --> EventsDB
    MessagesWrapper --> MessagesDB
    Blob --> Bucket

    Routes --> OpenAI
    OpenAI --> Routes

    Handler --> CloudWatch

    click Handler "https://github.com/meyer1994/wa/blob/main/handler.py"
    click App "https://github.com/meyer1994/wa/blob/main/wa/app.py"
    click Routes "https://github.com/meyer1994/wa/blob/main/wa/routes.py"
    click Lifespan "https://github.com/meyer1994/wa/blob/main/wa/lifespan.py"
    click Logs "https://github.com/meyer1994/wa/blob/main/wa/logs.py"
    click MainAgent "https://github.com/meyer1994/wa/blob/main/wa/agents/main.py"
    click LogAgent "https://github.com/meyer1994/wa/blob/main/wa/agents/log.py"
    click MathAgent "https://github.com/meyer1994/wa/blob/main/wa/agents/math.py"
    click TodoAgent "https://github.com/meyer1994/wa/blob/main/wa/agents/todos.py"
    click MessagesWrapper "https://github.com/meyer1994/wa/blob/main/wa/dynamo/messages.py"
    click EventsWrapper "https://github.com/meyer1994/wa/blob/main/wa/dynamo/tools.py"
    click WhatsappWrapper "https://github.com/meyer1994/wa/blob/main/wa/dynamo/whatsapp.py"
    click Blob "https://github.com/meyer1994/wa/blob/main/wa/blob.py"
    click WhatsClient "https://github.com/meyer1994/wa/blob/main/wa/whats/client.py"
    click WhatsModels "https://github.com/meyer1994/wa/blob/main/wa/whats/models.py"

    classDef compute fill:#ADD8E6,stroke:#000;
    classDef aws fill:#FFA500,stroke:#000;
    classDef external fill:#90EE90,stroke:#000;
```
