# pricardok/agente-sdr-comercial architecture

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

- Interactive diagram: https://gitdiagram.com/pricardok/agente-sdr-comercial
- Repository: https://github.com/pricardok/agente-sdr-comercial

## Overview

This is a FastAPI commercial SDR agent that processes WhatsApp leads delivered through Chatwoot, qualifies them with an LLM, and replies or hands them to a human. The documented workflow includes webhook filtering, pause/duplicate checks, conversation memory, debounce, knowledge grounding, and handoff alerts. The graph includes the principal database and optional customer lookup. Some service implementation is only partially excerpted, so the README and source index support several documented links; unsampled internals are not inferred.

Main entry points: [`app/services/sdr_service.py`](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/sdr_service.py) (SDR workflow), [`app/routes/sdr_routes.py`](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/routes/sdr_routes.py) (Webhook route), [`app/database/database_core.py`](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/database/database_core.py) (Lead memory database), [`app/config/settings.py`](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/config/settings.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Webhook entry"]
  node_api["FastAPI app<br/>[main.py]"]
  node_webhook["Webhook route<br/>[sdr_routes.py]"]
  node_payload["Webhook schema<br/>[webhook.py]"]
end

subgraph group_conversation["Conversation processing"]
  node_sdr["SDR workflow<br/>[sdr_service.py]"]
  node_debounce["Message debounce"]
  node_knowledge["Sales knowledge"]
  node_tool["Human handoff tool<br/>[tools.py]"]
  node_normalization["Phone normalization<br/>[normalizacao.py]"]
end

subgraph group_state["Conversation state"]
  node_primary_db[("Lead memory database<br/>[database_core.py]")]
  node_conversation_model["Conversation records<br/>[conversa.py]"]
  node_message_model["Message records<br/>[mensagem.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_secondary_db[("Optional customer lookup<br/>[database_core.py]")]
end

subgraph group_integrations["External integrations"]
  node_litellm{{"LiteLLM gateway"}}
  node_chatwoot_api["Chatwoot API client"]
  node_alert["Handoff alert service<br/>[alerta_service.py]"]
end

node_chatwoot_actor(("WhatsApp / Chatwoot"))

node_chatwoot_actor -->|"sends events"| node_webhook
node_api -->|"registers route"| node_webhook
node_webhook -->|"validates payload"| node_payload
node_webhook -->|"dispatches event"| node_sdr
node_webhook -->|"provides session"| node_primary_db
node_sdr -->|"buffers messages"| node_debounce
node_sdr -->|"loads context"| node_knowledge
node_sdr -->|"requests response"| node_litellm
node_sdr -->|"handles transfer tool"| node_tool
node_sdr -->|"normalizes phone"| node_normalization
node_sdr -->|"reads and writes memory"| node_primary_db
node_primary_db -->|"persists conversations"| node_conversation_model
node_primary_db -->|"persists messages"| node_message_model
node_sdr -->|"checks customer status"| node_secondary_db
node_sdr -->|"checks tags and sends"| node_chatwoot_api
node_chatwoot_api -->|"calls REST API"| node_chatwoot_actor
node_sdr -->|"dispatches handoff alert"| node_alert
node_settings -->|"configures connection"| node_primary_db
node_settings -->|"configures optional connection"| node_secondary_db

click node_api "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/main.py"
click node_webhook "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/routes/sdr_routes.py"
click node_payload "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/schemas/webhook.py"
click node_sdr "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/sdr_service.py"
click node_debounce "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/debounce_service.py"
click node_knowledge "https://github.com/pricardok/agente-sdr-comercial/tree/main/knowledge"
click node_tool "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/schemas/tools.py"
click node_normalization "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/utils/normalizacao.py"
click node_chatwoot_api "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/chatwoot_service.py"
click node_alert "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/alerta_service.py"
click node_primary_db "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/database/database_core.py"
click node_conversation_model "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/models/conversa.py"
click node_message_model "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/models/mensagem.py"
click node_settings "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/config/settings.py"
click node_secondary_db "https://github.com/pricardok/agente-sdr-comercial/blob/main/app/database/database_core.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_api,node_webhook,node_payload toneBlue
class node_sdr,node_debounce,node_knowledge,node_tool,node_normalization toneAmber
class node_primary_db,node_conversation_model,node_message_model,node_settings,node_secondary_db toneMint
class node_litellm,node_chatwoot_api,node_alert toneRose
class node_chatwoot_actor toneIndigo
```

## Components

### Webhook entry

- [FastAPI app](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/main.py): `app/main.py`
- [Webhook route](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/routes/sdr_routes.py): `app/routes/sdr_routes.py`
- [Webhook schema](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/schemas/webhook.py): `app/schemas/webhook.py`

### Conversation processing

- [SDR workflow](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/sdr_service.py): `app/services/sdr_service.py`
- [Message debounce](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/debounce_service.py): `app/services/debounce_service.py`
- [Sales knowledge](https://github.com/pricardok/agente-sdr-comercial/tree/main/knowledge): `knowledge`
- [Human handoff tool](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/schemas/tools.py): `app/schemas/tools.py`
- [Phone normalization](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/utils/normalizacao.py): `app/utils/normalizacao.py`

### Conversation state

- [Lead memory database](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/database/database_core.py): `app/database/database_core.py`
- [Conversation records](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/models/conversa.py): `app/models/conversa.py`
- [Message records](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/models/mensagem.py): `app/models/mensagem.py`
- [Runtime settings](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/config/settings.py): `app/config/settings.py`
- [Optional customer lookup](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/database/database_core.py): `app/database/database_core.py`

### External integrations

- **LiteLLM gateway**
- [Chatwoot API client](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/chatwoot_service.py): `app/services/chatwoot_service.py`
- [Handoff alert service](https://github.com/pricardok/agente-sdr-comercial/blob/main/app/services/alerta_service.py): `app/services/alerta_service.py`

### Other components

- **WhatsApp / Chatwoot**

## Connections

- WhatsApp / Chatwoot → Webhook route: sends events (evidence: `README.md`)
- FastAPI app → Webhook route: registers route (evidence: `app/main.py`)
- Webhook route → Webhook schema: validates payload (evidence: `app/routes/sdr_routes.py`)
- Webhook route → SDR workflow: dispatches event (evidence: `app/routes/sdr_routes.py`)
- Webhook route → Lead memory database: provides session (evidence: `app/routes/sdr_routes.py`)
- SDR workflow → Message debounce: buffers messages (evidence: `README.md`)
- SDR workflow → Sales knowledge: loads context (evidence: `README.md`)
- SDR workflow → LiteLLM gateway: requests response (evidence: `README.md`)
- SDR workflow → Human handoff tool: handles transfer tool (evidence: `README.md`)
- SDR workflow → Phone normalization: normalizes phone (evidence: `app/services/sdr_service.py`)
- SDR workflow → Lead memory database: reads and writes memory (evidence: `app/services/sdr_service.py`)
- Lead memory database → Conversation records: persists conversations (evidence: `app/database/init_schema.py`)
- Lead memory database → Message records: persists messages (evidence: `app/database/init_schema.py`)
- SDR workflow → Optional customer lookup: checks customer status (evidence: `app/services/sdr_service.py`)
- SDR workflow → Chatwoot API client: checks tags and sends (evidence: `app/services/sdr_service.py`)
- Chatwoot API client → WhatsApp / Chatwoot: calls REST API (evidence: `app/services/chatwoot_service.py`)
- SDR workflow → Handoff alert service: dispatches handoff alert (evidence: `app/services/sdr_service.py`)
- Runtime settings → Lead memory database: configures connection (evidence: `app/database/database_core.py`)
- Runtime settings → Optional customer lookup: configures optional connection (evidence: `app/database/database_core.py`)
