# asimov-academy/agente-whatsapp architecture

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

- Interactive diagram: https://gitdiagram.com/asimov-academy/agente-whatsapp
- Repository: https://github.com/asimov-academy/agente-whatsapp

## Overview

Duda é um agente de atendimento pelo WhatsApp. O fluxo principal recebe mensagens via WAHA, converte áudio, imagem e PDF em texto, reúne mensagens fragmentadas, consulta o histórico e o agente, e envia uma resposta curta com sinais de leitura e digitação. O terminal oferece uma interface alternativa. Os módulos centrais estão representados; relações entre arquivos foram incluídas quando aparecem nos trechos, no índice de referências ou no README. Integrações com serviços externos estão separadas.

Main entry points: [`app/ritmo.py`](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/ritmo.py) (Buffer e ritmo), [`app/midia.py`](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/midia.py) (Conversão de mídia), [`app/main.py`](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/main.py) (Webhook), [`app/agent.py`](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/agent.py) (Agente Duda)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channel["Canal WhatsApp"]
  node_webhook["Webhook<br/>[main.py]"]
  node_whatsapp_api["API WhatsApp<br/>[whatsapp.py]"]
end

subgraph group_flow["Fluxo de conversa"]
  node_rhythm["Buffer e ritmo<br/>[ritmo.py]"]
  node_terminal["Chat terminal<br/>[chat.py]"]
end

subgraph group_intelligence["Agente e mídia"]
  node_media["Conversão de mídia<br/>[midia.py]"]
  node_agent["Agente Duda<br/>[agent.py]"]
  node_prompt["Personalidade e limites<br/>[system_prompt.md]"]
end

subgraph group_state["Configuração e estado"]
  node_history[("Histórico por contato<br/>[memory.py]")]
  node_config["Configuração<br/>[config.py]"]
end

node_customer(("Cliente"))
node_waha{{"WAHA"}}
node_openrouter{{"OpenRouter"}}

node_customer -->|"envia mensagens"| node_waha
node_waha -->|"envia webhook"| node_webhook
node_webhook -->|"converte anexos"| node_media
node_webhook -->|"adiciona mensagem"| node_rhythm
node_media -->|"baixa arquivos"| node_waha
node_media -->|"transcreve e descreve"| node_openrouter
node_rhythm -->|"consulta agente"| node_agent
node_rhythm -->|"lê e grava"| node_history
node_rhythm -->|"resume para histórico"| node_media
node_rhythm -->|"sinaliza e envia"| node_whatsapp_api
node_whatsapp_api -->|"chama API"| node_waha
node_waha -->|"entrega resposta"| node_customer
node_agent -->|"carrega instruções"| node_prompt
node_agent -->|"gera resposta"| node_openrouter
node_terminal -->|"consulta agente"| node_agent
node_terminal -->|"lê e grava"| node_history
node_terminal -->|"divide resposta"| node_rhythm
node_webhook -->|"carrega configuração"| node_config
node_media -->|"usa credenciais"| node_config
node_whatsapp_api -->|"usa credenciais"| node_config
node_rhythm -->|"usa intervalo"| node_config

click node_webhook "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/main.py"
click node_whatsapp_api "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/whatsapp.py"
click node_rhythm "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/ritmo.py"
click node_terminal "https://github.com/asimov-academy/agente-whatsapp/blob/main/chat.py"
click node_media "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/midia.py"
click node_agent "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/agent.py"
click node_prompt "https://github.com/asimov-academy/agente-whatsapp/blob/main/prompts/system_prompt.md"
click node_history "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/memory.py"
click node_config "https://github.com/asimov-academy/agente-whatsapp/blob/main/app/config.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_webhook,node_whatsapp_api,node_customer toneBlue
class node_rhythm,node_terminal toneAmber
class node_media,node_agent,node_prompt,node_openrouter toneMint
class node_history,node_config toneRose
class node_waha toneIndigo
```

## Components

### Canal WhatsApp

- [Webhook](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/main.py): `app/main.py`
- [API WhatsApp](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/whatsapp.py): `app/whatsapp.py`

### Fluxo de conversa

- [Buffer e ritmo](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/ritmo.py): `app/ritmo.py`
- [Chat terminal](https://github.com/asimov-academy/agente-whatsapp/blob/main/chat.py): `chat.py`

### Agente e mídia

- [Conversão de mídia](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/midia.py): `app/midia.py`
- [Agente Duda](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/agent.py): `app/agent.py`
- [Personalidade e limites](https://github.com/asimov-academy/agente-whatsapp/blob/main/prompts/system_prompt.md): `prompts/system_prompt.md`

### Configuração e estado

- [Histórico por contato](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/memory.py): `app/memory.py`
- [Configuração](https://github.com/asimov-academy/agente-whatsapp/blob/main/app/config.py): `app/config.py`

### Other components

- **Cliente**
- **WAHA**
- **OpenRouter**

## Connections

- Cliente → WAHA: envia mensagens (evidence: `README.md`)
- WAHA → Webhook: envia webhook (evidence: `README.md`)
- Webhook → Conversão de mídia: converte anexos (evidence: `app/main.py`)
- Webhook → Buffer e ritmo: adiciona mensagem (evidence: `app/main.py`)
- Conversão de mídia → WAHA: baixa arquivos (evidence: `app/midia.py`)
- Conversão de mídia → OpenRouter: transcreve e descreve (evidence: `app/midia.py`)
- Buffer e ritmo → Agente Duda: consulta agente (evidence: `app/ritmo.py`)
- Buffer e ritmo → Histórico por contato: lê e grava (evidence: `app/ritmo.py`)
- Buffer e ritmo → Conversão de mídia: resume para histórico (evidence: `app/ritmo.py`)
- Buffer e ritmo → API WhatsApp: sinaliza e envia (evidence: `app/ritmo.py`)
- API WhatsApp → WAHA: chama API (evidence: `app/whatsapp.py`)
- WAHA → Cliente: entrega resposta (evidence: `README.md`)
- Agente Duda → Personalidade e limites: carrega instruções (evidence: `app/agent.py`)
- Agente Duda → OpenRouter: gera resposta (evidence: `README.md`)
- Chat terminal → Agente Duda: consulta agente (evidence: `chat.py`)
- Chat terminal → Histórico por contato: lê e grava (evidence: `chat.py`)
- Chat terminal → Buffer e ritmo: divide resposta (evidence: `chat.py`)
- Webhook → Configuração: carrega configuração (evidence: `app/main.py`)
- Conversão de mídia → Configuração: usa credenciais (evidence: `app/midia.py`)
- API WhatsApp → Configuração: usa credenciais (evidence: `app/whatsapp.py`)
- Buffer e ritmo → Configuração: usa intervalo (evidence: `app/ritmo.py`)
