# lgesuellip/langgraph-whatsapp-agent architecture

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

- Interactive diagram: https://gitdiagram.com/lgesuellip/langgraph-whatsapp-agent
- Repository: https://github.com/lgesuellip/langgraph-whatsapp-agent

## Overview

This template carries WhatsApp text and images through a Twilio-validated webhook to a LangGraph-hosted assistant, then formats the assistant reply as TwiML. Its agent template builds a supervisor with a calendar sub-agent and optional MCP tools. README-documented persistence, multimodal support, tracing, and deployment are included; where their implementation is not shown, links are limited to documented integrations.

Main entry points: [`src/agents/base/graph.py`](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py) (Supervisor graph), [`src/langgraph_whatsapp/server.py`](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/server.py) (Webhook server), [`src/langgraph_whatsapp/channel.py`](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/channel.py) (Message channel), [`src/langgraph_whatsapp/agent.py`](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/agent.py) (Graph client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["WhatsApp ingress"]
  node_server["Webhook server<br/>[server.py]"]
  node_validation["Signature validation<br/>[server.py]"]
  node_channel["Message channel<br/>[channel.py]"]
  node_media["Image retrieval<br/>[channel.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_agent_client["Graph client<br/>[agent.py]"]
  node_graph_builder["Supervisor graph<br/>[graph.py]"]
  node_supervisor["Supervisor agent<br/>[graph.py]"]
  node_calendar_agent["Calendar agent<br/>[graph.py]"]
  node_prompts["Agent prompts<br/>[prompt.py]"]
end

subgraph group_integrations["Agent integrations"]
  node_model["Gemini model"]
  node_zapier["Zapier MCP"]
  node_supermemory["Supermemory MCP"]
end

subgraph group_operations["Platform services"]
  node_platform["LangGraph Platform"]
  node_state[("Conversation state")]
  node_langsmith["LangSmith tracing"]
  node_auth["Platform auth<br/>[auth.py]"]
end

node_user(("WhatsApp user"))
node_twilio["Twilio WhatsApp"]

node_user -->|"sends messages"| node_twilio
node_twilio -->|"posts webhook"| node_server
node_server -->|"validates signature"| node_validation
node_server -->|"handles request"| node_channel
node_channel -->|"downloads images"| node_media
node_media -->|"fetches media"| node_twilio
node_channel -->|"invokes assistant"| node_agent_client
node_agent_client -->|"streams run"| node_platform
node_platform -->|"runs graph"| node_graph_builder
node_graph_builder -->|"builds supervisor"| node_supervisor
node_graph_builder -->|"builds sub-agent"| node_calendar_agent
node_graph_builder -->|"renders prompts"| node_prompts
node_graph_builder -->|"configures model"| node_model
node_graph_builder -.->|"loads tools"| node_zapier
node_graph_builder -.->|"loads tools"| node_supermemory
node_supervisor -->|"delegates scheduling"| node_calendar_agent
node_agent_client -->|"uses thread ID"| node_state
node_platform -->|"persists conversation"| node_state
node_platform -.->|"traces runs"| node_langsmith
node_platform -.->|"authenticates requests"| node_auth
node_platform -->|"returns result"| node_agent_client
node_agent_client -->|"returns reply"| node_channel
node_channel -->|"returns TwiML"| node_server
node_server -->|"responds webhook"| node_twilio
node_twilio -->|"delivers reply"| node_user

click node_server "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/server.py"
click node_validation "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/server.py"
click node_channel "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/channel.py"
click node_media "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/channel.py"
click node_agent_client "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/agent.py"
click node_graph_builder "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py"
click node_supervisor "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py"
click node_calendar_agent "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py"
click node_prompts "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/prompt.py"
click node_auth "https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/auth.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_server,node_validation,node_channel,node_media,node_user toneBlue
class node_agent_client,node_graph_builder,node_supervisor,node_calendar_agent,node_prompts toneAmber
class node_model,node_zapier,node_supermemory toneMint
class node_platform,node_state,node_langsmith,node_auth toneRose
class node_twilio toneIndigo
```

## Components

### WhatsApp ingress

- [Webhook server](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/server.py): `src/langgraph_whatsapp/server.py`
- [Signature validation](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/server.py): `src/langgraph_whatsapp/server.py`
- [Message channel](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/channel.py): `src/langgraph_whatsapp/channel.py`
- [Image retrieval](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/channel.py): `src/langgraph_whatsapp/channel.py`

### Agent runtime

- [Graph client](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/agent.py): `src/langgraph_whatsapp/agent.py`
- [Supervisor graph](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py): `src/agents/base/graph.py`
- [Supervisor agent](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py): `src/agents/base/graph.py`
- [Calendar agent](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/graph.py): `src/agents/base/graph.py`
- [Agent prompts](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/agents/base/prompt.py): `src/agents/base/prompt.py`

### Agent integrations

- **Gemini model**
- **Zapier MCP**
- **Supermemory MCP**

### Platform services

- **LangGraph Platform**
- **Conversation state**
- **LangSmith tracing**
- [Platform auth](https://github.com/lgesuellip/langgraph-whatsapp-agent/blob/main/src/langgraph_whatsapp/auth.py): `src/langgraph_whatsapp/auth.py`

### Other components

- **WhatsApp user**
- **Twilio WhatsApp**

## Connections

- WhatsApp user → Twilio WhatsApp: sends messages
- Twilio WhatsApp → Webhook server: posts webhook
- Webhook server → Signature validation: validates signature
- Webhook server → Message channel: handles request
- Message channel → Image retrieval: downloads images
- Image retrieval → Twilio WhatsApp: fetches media
- Message channel → Graph client: invokes assistant
- Graph client → LangGraph Platform: streams run
- LangGraph Platform → Supervisor graph: runs graph
- Supervisor graph → Supervisor agent: builds supervisor
- Supervisor graph → Calendar agent: builds sub-agent
- Supervisor graph → Agent prompts: renders prompts
- Supervisor graph → Gemini model: configures model
- Supervisor graph → Zapier MCP: loads tools
- Supervisor graph → Supermemory MCP: loads tools
- Supervisor agent → Calendar agent: delegates scheduling
- Graph client → Conversation state: uses thread ID
- LangGraph Platform → Conversation state: persists conversation
- LangGraph Platform → LangSmith tracing: traces runs
- LangGraph Platform → Platform auth: authenticates requests
- LangGraph Platform → Graph client: returns result
- Graph client → Message channel: returns reply
- Message channel → Webhook server: returns TwiML
- Webhook server → Twilio WhatsApp: responds webhook
- Twilio WhatsApp → WhatsApp user: delivers reply