# devthayron/whatsapp-ai-agent architecture

> Architecture diagram of the GitHub repository devthayron/whatsapp-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devthayron/whatsapp-ai-agent
- Repository: https://github.com/devthayron/whatsapp-ai-agent
- Video tour (about a minute): https://gitdiagram.com/devthayron/whatsapp-ai-agent/video

## Overview

This is a FastAPI WhatsApp AI agent: incoming messages are normalized, associated with a user, combined with persisted or initially imported conversation history, sent to OpenAI, saved, and returned through Evolution API. The direct chat endpoint shares the agent workflow. The README documents history synchronization, duplicate-message handling, and persistent SQLite storage; unsampled model and schema details are represented only at their documented paths.

Main entry points: [`services/agent.py`](https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/agent.py) (Conversation agent), [`database/conversations.py`](https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/conversations.py) (History and messages), [`services/evolution.py`](https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/evolution.py) (Evolution integration), [`app/routes/webhook.py`](https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/routes/webhook.py) (Webhook route)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API ingress"]
  node_application["FastAPI application<br/>[main.py]"]
  node_webhook_route["Webhook route<br/>[webhook.py]"]
  node_chat_route["Chat route<br/>[chat.py]"]
end

subgraph group_conversation["Conversation processing"]
  node_message_processor["Message normalization"]
  node_agent["Conversation agent<br/>[agent.py]"]
end

subgraph group_integrations["External integrations"]
  node_evolution_service["Evolution integration<br/>[evolution.py]"]
  node_openai_service["OpenAI integration<br/>[openai.py]"]
end

subgraph group_persistence["Persistence"]
  node_user_service["User identification<br/>[users.py]"]
  node_conversation_service["History and messages<br/>[conversations.py]"]
  node_database_models[("Conversation database<br/>[models.py]")]
  node_database_connection["Database connection<br/>[connection.py]"]
end

node_whatsapp(("WhatsApp user"))
node_evolution_external["Evolution API"]
node_openai_external["OpenAI"]
node_chat_client(("Chat API client"))

node_whatsapp -->|"sends messages"| node_evolution_external
node_evolution_external -->|"delivers webhook"| node_webhook_route
node_webhook_route -->|"extracts and normalizes"| node_message_processor
node_webhook_route -->|"processes message"| node_agent
node_agent -->|"identifies user"| node_user_service
node_agent -->|"ensures history"| node_conversation_service
node_agent -->|"saves message"| node_conversation_service
node_agent -->|"loads context"| node_conversation_service
node_conversation_service -->|"imports initial history"| node_evolution_service
node_conversation_service -->|"finds or creates user"| node_user_service
node_user_service -->|"reads and writes users"| node_database_models
node_conversation_service -->|"reads and writes messages"| node_database_models
node_application -->|"creates tables"| node_database_connection
node_database_connection -->|"configures persistence"| node_database_models
node_agent -->|"generates response"| node_openai_service
node_openai_service -->|"requests completion"| node_openai_external
node_webhook_route -->|"sends reply"| node_evolution_service
node_chat_client -->|"submits message"| node_chat_route
node_chat_route -->|"processes message"| node_agent
node_chat_route -->|"sends reply"| node_evolution_service
node_evolution_service -->|"fetches history"| node_evolution_external
node_evolution_service -->|"sends WhatsApp message"| node_evolution_external

click node_application "https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/main.py"
click node_webhook_route "https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/routes/webhook.py"
click node_chat_route "https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/routes/chat.py"
click node_message_processor "https://github.com/devthayron/whatsapp-ai-agent/blob/main/bot/message_processor.py"
click node_agent "https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/agent.py"
click node_user_service "https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/users.py"
click node_conversation_service "https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/conversations.py"
click node_database_models "https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/models.py"
click node_database_connection "https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/connection.py"
click node_evolution_service "https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/evolution.py"
click node_openai_service "https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/openai.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_application,node_webhook_route,node_chat_route,node_whatsapp,node_chat_client toneBlue
class node_message_processor,node_agent toneAmber
class node_evolution_service,node_openai_service,node_evolution_external toneMint
class node_user_service,node_conversation_service,node_database_models,node_database_connection toneRose
class node_openai_external toneIndigo
```

## Components

### API ingress

- [FastAPI application](https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/main.py): `app/main.py`
- [Webhook route](https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/routes/webhook.py): `app/routes/webhook.py`
- [Chat route](https://github.com/devthayron/whatsapp-ai-agent/blob/main/app/routes/chat.py): `app/routes/chat.py`

### Conversation processing

- [Message normalization](https://github.com/devthayron/whatsapp-ai-agent/blob/main/bot/message_processor.py): `bot/message_processor.py`
- [Conversation agent](https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/agent.py): `services/agent.py`

### External integrations

- [Evolution integration](https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/evolution.py): `services/evolution.py`
- [OpenAI integration](https://github.com/devthayron/whatsapp-ai-agent/blob/main/services/openai.py): `services/openai.py`

### Persistence

- [User identification](https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/users.py): `database/users.py`
- [History and messages](https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/conversations.py): `database/conversations.py`
- [Conversation database](https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/models.py): `database/models.py`
- [Database connection](https://github.com/devthayron/whatsapp-ai-agent/blob/main/database/connection.py): `database/connection.py`

### Other components

- **WhatsApp user**
- **Evolution API**
- **OpenAI**
- **Chat API client**

## Connections

- WhatsApp user → Evolution API: sends messages
- Evolution API → Webhook route: delivers webhook
- Webhook route → Message normalization: extracts and normalizes
- Webhook route → Conversation agent: processes message
- Conversation agent → User identification: identifies user
- Conversation agent → History and messages: ensures history
- Conversation agent → History and messages: saves message
- Conversation agent → History and messages: loads context
- History and messages → Evolution integration: imports initial history
- History and messages → User identification: finds or creates user
- User identification → Conversation database: reads and writes users
- History and messages → Conversation database: reads and writes messages
- FastAPI application → Database connection: creates tables
- Database connection → Conversation database: configures persistence
- Conversation agent → OpenAI integration: generates response
- OpenAI integration → OpenAI: requests completion
- Webhook route → Evolution integration: sends reply
- Chat API client → Chat route: submits message
- Chat route → Conversation agent: processes message
- Chat route → Evolution integration: sends reply
- Evolution integration → Evolution API: fetches history
- Evolution integration → Evolution API: sends WhatsApp message