# ahmedsheikh27/auto-whatsapp architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedsheikh27/auto-whatsapp
- Repository: https://github.com/ahmedsheikh27/auto-whatsapp

## Overview

This is a WhatsApp sales assistant paired with a product-browsing website and a shared FastAPI backend. The main messaging workflow verifies and receives WhatsApp webhooks, identifies the customer, saves the incoming message, delegates to the conversational agent, saves the reply, and sends it back. The backend also serves product and collection browsing. The graph includes the SDK and persistence layer; unsampled agent and service internals are represented only where the tree or source index supports them.

Main entry points: [`backend/app/agents/main_agent.py`](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/main_agent.py) (Conversation orchestrator), [`backend/app/api/webhook.py`](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/webhook.py) (WhatsApp webhook), [`backend/app/sdk/client.py`](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/sdk/client.py) (Ecommerce SDK), [`backend/app/main.py`](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web storefront"]
  node_web_pages["Storefront pages"]
  node_product_ui["Product browsing UI<br/>[ProductsClient.tsx]"]
  node_collection_ui["Collection browsing UI<br/>[page.tsx]"]
  node_web_api["Backend fetch client<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_app_entry["FastAPI app<br/>[main.py]"]
  node_webhook["WhatsApp webhook<br/>[webhook.py]"]
  node_product_routes["Product routes<br/>[products.py]"]
  node_collection_routes["Collection routes<br/>[collection.py]"]
  node_message_routes["Message routes<br/>[messages.py]"]
  node_whatsapp_service["WhatsApp sender"]
end

subgraph group_agents["Conversation agents"]
  node_main_agent["Conversation orchestrator<br/>[main_agent.py]"]
  node_faq_agent["FAQ agent<br/>[faq_agent.py]"]
  node_product_agent["Product agent<br/>[product_agent.py]"]
  node_order_agent["Order agent<br/>[order_agent.py]"]
  node_order_tool["Order tool<br/>[order_tool.py]"]
  node_faq_tool["FAQ tool<br/>[faq_tool.py]"]
  node_product_tool["Product tool<br/>[product_tool.py]"]
  node_llm_config["LLM configuration<br/>[config.py]"]
end

subgraph group_commerce["Commerce SDK"]
  node_sdk["Ecommerce SDK<br/>[client.py]"]
  node_postgres_adapter["Postgres adapter<br/>[postgres.py]"]
end

subgraph group_data["State and storage"]
  node_models["Commerce models<br/>[tables.py]"]
  node_postgres[("PostgreSQL")]
  node_session_service["Conversation sessions<br/>[session_service.py]"]
  node_redis[("Redis")]
end

node_shopper(("Shopper"))
node_whatsapp_customer(("WhatsApp customer"))
node_whatsapp["WhatsApp Cloud API"]

node_shopper -->|"browses"| node_web_pages
node_web_pages -.->|"shows products"| node_product_ui
node_web_pages -->|"shows collections"| node_collection_ui
node_product_ui -->|"uses fetch client"| node_web_api
node_collection_ui -->|"fetches collections"| node_web_api
node_web_api -->|"requests products"| node_product_routes
node_web_api -->|"requests collections"| node_collection_routes
node_whatsapp_customer -->|"messages"| node_whatsapp
node_whatsapp -->|"posts events"| node_webhook
node_app_entry -->|"registers route"| node_webhook
node_app_entry -->|"registers route"| node_product_routes
node_app_entry -->|"registers route"| node_collection_routes
node_app_entry -->|"registers route"| node_message_routes
node_webhook -->|"creates SDK"| node_sdk
node_product_routes -->|"creates SDK"| node_sdk
node_collection_routes -->|"creates SDK"| node_sdk
node_webhook -->|"runs agent"| node_main_agent
node_webhook -->|"sends reply"| node_whatsapp_service
node_main_agent -->|"dispatches to"| node_faq_agent
node_main_agent -->|"dispatches to"| node_product_agent
node_main_agent -->|"dispatches to"| node_order_agent
node_main_agent -->|"uses session"| node_session_service
node_order_agent -->|"uses tool"| node_order_tool
node_order_tool -->|"creates orders"| node_sdk
node_main_agent -->|"uses settings"| node_llm_config
node_sdk -->|"constructs adapter"| node_postgres_adapter
node_postgres_adapter -->|"queries models"| node_models
node_postgres_adapter -->|"reads and writes"| node_postgres
node_session_service -->|"stores sessions"| node_redis
node_whatsapp_service -.->|"sends messages"| node_whatsapp

click node_web_pages "https://github.com/ahmedsheikh27/auto-whatsapp/tree/master/wa-front/app"
click node_product_ui "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/products/ProductsClient.tsx"
click node_collection_ui "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/collection/page.tsx"
click node_web_api "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/service/api.ts"
click node_app_entry "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/main.py"
click node_webhook "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/webhook.py"
click node_product_routes "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/products.py"
click node_collection_routes "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/collection.py"
click node_message_routes "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/messages.py"
click node_main_agent "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/main_agent.py"
click node_faq_agent "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/faq_agent.py"
click node_product_agent "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/product_agent.py"
click node_order_agent "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/order_agent.py"
click node_order_tool "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/order_tool.py"
click node_faq_tool "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/faq_tool.py"
click node_product_tool "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/product_tool.py"
click node_sdk "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/sdk/client.py"
click node_postgres_adapter "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/sdk/adapters/postgres.py"
click node_models "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/models/tables.py"
click node_session_service "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/services/session_service.py"
click node_whatsapp_service "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/services/whatsapp_service.py"
click node_llm_config "https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/core/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_web_pages,node_product_ui,node_collection_ui,node_web_api toneBlue
class node_app_entry,node_webhook,node_product_routes,node_collection_routes,node_message_routes,node_whatsapp_service toneAmber
class node_main_agent,node_faq_agent,node_product_agent,node_order_agent,node_order_tool,node_faq_tool,node_product_tool,node_llm_config,node_whatsapp toneMint
class node_sdk,node_postgres_adapter toneRose
class node_models,node_postgres,node_session_service,node_redis,node_shopper,node_whatsapp_customer toneIndigo
```

## Components

### Web storefront

- [Storefront pages](https://github.com/ahmedsheikh27/auto-whatsapp/tree/master/wa-front/app): `wa-front/app`
- [Product browsing UI](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/products/ProductsClient.tsx): `wa-front/app/products/ProductsClient.tsx`
- [Collection browsing UI](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/collection/page.tsx): `wa-front/app/collection/page.tsx`
- [Backend fetch client](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/wa-front/app/service/api.ts): `wa-front/app/service/api.ts`

### Backend API

- [FastAPI app](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/main.py): `backend/app/main.py`
- [WhatsApp webhook](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/webhook.py): `backend/app/api/webhook.py`
- [Product routes](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/products.py): `backend/app/api/products.py`
- [Collection routes](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/collection.py): `backend/app/api/collection.py`
- [Message routes](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/api/messages.py): `backend/app/api/messages.py`
- [WhatsApp sender](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/services/whatsapp_service.py): `backend/app/services/whatsapp_service.py`

### Conversation agents

- [Conversation orchestrator](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/main_agent.py): `backend/app/agents/main_agent.py`
- [FAQ agent](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/faq_agent.py): `backend/app/agents/faq_agent.py`
- [Product agent](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/product_agent.py): `backend/app/agents/product_agent.py`
- [Order agent](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/agents/order_agent.py): `backend/app/agents/order_agent.py`
- [Order tool](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/order_tool.py): `backend/app/tools/order_tool.py`
- [FAQ tool](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/faq_tool.py): `backend/app/tools/faq_tool.py`
- [Product tool](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/tools/product_tool.py): `backend/app/tools/product_tool.py`
- [LLM configuration](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/core/config.py): `backend/app/core/config.py`

### Commerce SDK

- [Ecommerce SDK](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/sdk/client.py): `backend/app/sdk/client.py`
- [Postgres adapter](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/sdk/adapters/postgres.py): `backend/app/sdk/adapters/postgres.py`

### State and storage

- [Commerce models](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/models/tables.py): `backend/app/models/tables.py`
- **PostgreSQL**
- [Conversation sessions](https://github.com/ahmedsheikh27/auto-whatsapp/blob/master/backend/app/services/session_service.py): `backend/app/services/session_service.py`
- **Redis**

### Other components

- **Shopper**
- **WhatsApp customer**
- **WhatsApp Cloud API**

## Connections

- Shopper → Storefront pages: browses
- Storefront pages → Product browsing UI: shows products (evidence: `wa-front/app/products/page.tsx`)
- Storefront pages → Collection browsing UI: shows collections (evidence: `wa-front/app/collection/page.tsx`)
- Product browsing UI → Backend fetch client: uses fetch client (evidence: `wa-front/app/products/page.tsx`)
- Collection browsing UI → Backend fetch client: fetches collections (evidence: `wa-front/app/collection/page.tsx`)
- Backend fetch client → Product routes: requests products (evidence: `wa-front/app/service/api.ts`)
- Backend fetch client → Collection routes: requests collections (evidence: `wa-front/app/service/api.ts`)
- WhatsApp customer → WhatsApp Cloud API: messages
- WhatsApp Cloud API → WhatsApp webhook: posts events
- FastAPI app → WhatsApp webhook: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Product routes: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Collection routes: registers route (evidence: `backend/app/main.py`)
- FastAPI app → Message routes: registers route (evidence: `backend/app/main.py`)
- WhatsApp webhook → Ecommerce SDK: creates SDK (evidence: `backend/app/api/webhook.py`)
- Product routes → Ecommerce SDK: creates SDK (evidence: `backend/app/api/products.py`)
- Collection routes → Ecommerce SDK: creates SDK (evidence: `backend/app/api/collection.py`)
- WhatsApp webhook → Conversation orchestrator: runs agent (evidence: `backend/app/api/webhook.py`)
- WhatsApp webhook → WhatsApp sender: sends reply (evidence: `backend/app/api/webhook.py`)
- Conversation orchestrator → FAQ agent: dispatches to (evidence: `backend/app/agents/main_agent.py`)
- Conversation orchestrator → Product agent: dispatches to (evidence: `backend/app/agents/main_agent.py`)
- Conversation orchestrator → Order agent: dispatches to (evidence: `backend/app/agents/main_agent.py`)
- Conversation orchestrator → Conversation sessions: uses session (evidence: `backend/app/agents/main_agent.py`)
- Order agent → Order tool: uses tool (evidence: `backend/app/agents/order_agent.py`)
- Order tool → Ecommerce SDK: creates orders (evidence: `backend/app/tools/order_tool.py`)
- Conversation orchestrator → LLM configuration: uses settings (evidence: `backend/app/agents/main_agent.py`)
- Ecommerce SDK → Postgres adapter: constructs adapter (evidence: `backend/app/sdk/client.py`)
- Postgres adapter → Commerce models: queries models (evidence: `backend/app/sdk/adapters/postgres.py`)
- Postgres adapter → PostgreSQL: reads and writes (evidence: `backend/app/sdk/adapters/postgres.py`)
- Conversation sessions → Redis: stores sessions (evidence: `backend/app/services/session_service.py`)
- WhatsApp sender → WhatsApp Cloud API: sends messages
