# sohaggain/ai-omnichannel-support-agent architecture

> Architecture diagram of the GitHub repository sohaggain/ai-omnichannel-support-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/sohaggain/ai-omnichannel-support-agent
- Repository: https://github.com/sohaggain/ai-omnichannel-support-agent

## Overview

This is a FastAPI customer-support service that accepts website, WhatsApp, email, and Messenger messages and routes them through one Claude-based agent. The agent loads conversation context, may retrieve grounded knowledge, create an internal ticket, or escalate to a human, then persists and returns a reply through the originating channel. The README also documents optional CRM mirroring and n8n automations. The supplied source excerpts show the orchestrator, CRM, RAG, and several integration clients; some channel, tool, and vector-store wiring is documented but not sampled, so uncertain links are omitted.

Main entry points: [`src/agent/orchestrator.py`](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/orchestrator.py) (Agent orchestrator), [`src/main.py`](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/main.py) (FastAPI app), [`src/crm/service.py`](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/crm/service.py) (CRM service), [`src/agent/tools.py`](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/tools.py) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Channels"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_website["Website adapter"]
  node_whatsapp["WhatsApp adapter"]
  node_email["Email adapter"]
  node_messenger["Messenger adapter"]
end

subgraph group_agent["Agent workflow"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_tools["Agent tools<br/>[tools.py]"]
end

subgraph group_knowledge["Knowledge base"]
  node_ingestion["KB ingestion<br/>[ingest.py]"]
  node_retriever["KB retrieval<br/>[retriever.py]"]
  node_vectorstore[("Vector store<br/>[vectorstore.py]")]
end

subgraph group_records["Support records"]
  node_crm["CRM service<br/>[service.py]"]
  node_dbsession["DB sessions<br/>[session.py]"]
  node_recordsdb[("Support records<br/>[models.py]")]
end

subgraph group_integrations["External services"]
  node_claude["Anthropic Claude"]
  node_whatsappapi["WhatsApp API"]
  node_gmail["Gmail API"]
  node_messengerapi["Messenger API"]
  node_slack["Slack"]
  node_hubspot["HubSpot"]
  node_gohighlevel["GoHighLevel"]
  node_gmailclient["Gmail client<br/>[gmail_client.py]"]
  node_whatsappclient["WhatsApp client<br/>[whatsapp_client.py]"]
  node_messengerclient["Messenger client"]
  node_slackclient["Slack client<br/>[slack_client.py]"]
  node_hubspotclient["HubSpot client<br/>[hubspot_client.py]"]
  node_ghlclient["GoHighLevel client"]
  node_n8n["n8n workflows"]
end

node_customer(("Customer"))

node_customer -->|"sends message"| node_fastapi
node_fastapi -->|"routes request"| node_website
node_fastapi -->|"routes request"| node_whatsapp
node_fastapi -->|"routes request"| node_email
node_fastapi -->|"routes request"| node_messenger
node_website -->|"submits message"| node_orchestrator
node_whatsapp -->|"submits message"| node_orchestrator
node_email -->|"submits message"| node_orchestrator
node_messenger -->|"submits message"| node_orchestrator
node_orchestrator -->|"requests completion"| node_claude
node_orchestrator -->|"executes tools"| node_tools
node_tools -->|"searches knowledge"| node_retriever
node_ingestion -->|"upserts chunks"| node_vectorstore
node_retriever -->|"queries chunks"| node_vectorstore
node_orchestrator -->|"gets contact"| node_crm
node_orchestrator -->|"persists conversation"| node_dbsession
node_dbsession -->|"reads and writes"| node_recordsdb
node_crm -->|"writes tickets"| node_recordsdb
node_crm -.->|"mirrors ticket"| node_hubspotclient
node_crm -.->|"mirrors ticket"| node_ghlclient
node_hubspotclient -.->|"creates ticket"| node_hubspot
node_ghlclient -.->|"creates ticket"| node_gohighlevel
node_tools -->|"requests escalation"| node_slackclient
node_slackclient -->|"posts handoff"| node_slack
node_whatsappclient -->|"sends reply"| node_whatsappapi
node_messengerclient -->|"sends reply"| node_messengerapi
node_gmailclient -->|"sends reply"| node_gmail
node_n8n -.->|"optional follow-up"| node_slack

click node_fastapi "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/main.py"
click node_website "https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels"
click node_whatsapp "https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels"
click node_email "https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels"
click node_messenger "https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels"
click node_orchestrator "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/orchestrator.py"
click node_tools "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/tools.py"
click node_ingestion "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/ingest.py"
click node_retriever "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/retriever.py"
click node_vectorstore "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/vectorstore.py"
click node_crm "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/crm/service.py"
click node_dbsession "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/db/session.py"
click node_recordsdb "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/db/models.py"
click node_gmailclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/gmail_client.py"
click node_whatsappclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/whatsapp_client.py"
click node_messengerclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/messenger_client.py"
click node_slackclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/slack_client.py"
click node_hubspotclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/hubspot_client.py"
click node_ghlclient "https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/gohighlevel_client.py"
click node_n8n "https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/workflows/n8n"

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_fastapi,node_website,node_whatsapp,node_email,node_messenger toneBlue
class node_orchestrator,node_tools toneAmber
class node_ingestion,node_retriever,node_vectorstore toneMint
class node_crm,node_dbsession,node_recordsdb toneRose
class node_claude,node_whatsappapi,node_gmail,node_messengerapi,node_slack,node_hubspot,node_gohighlevel,node_gmailclient,node_whatsappclient,node_messengerclient,node_slackclient,node_hubspotclient,node_ghlclient,node_n8n,node_customer toneIndigo
```

## Components

### Channels

- [FastAPI app](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/main.py): `src/main.py`
- [Website adapter](https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels): `src/channels`
- [WhatsApp adapter](https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels): `src/channels`
- [Email adapter](https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels): `src/channels`
- [Messenger adapter](https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/src/channels): `src/channels`

### Agent workflow

- [Agent orchestrator](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/orchestrator.py): `src/agent/orchestrator.py`
- [Agent tools](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/agent/tools.py): `src/agent/tools.py`

### Knowledge base

- [KB ingestion](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/ingest.py): `src/rag/ingest.py`
- [KB retrieval](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/retriever.py): `src/rag/retriever.py`
- [Vector store](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/rag/vectorstore.py): `src/rag/vectorstore.py`

### Support records

- [CRM service](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/crm/service.py): `src/crm/service.py`
- [DB sessions](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/db/session.py): `src/db/session.py`
- [Support records](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/db/models.py): `src/db/models.py`

### External services

- **Anthropic Claude**
- **WhatsApp API**
- **Gmail API**
- **Messenger API**
- **Slack**
- **HubSpot**
- **GoHighLevel**
- [Gmail client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/gmail_client.py): `src/integrations/gmail_client.py`
- [WhatsApp client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/whatsapp_client.py): `src/integrations/whatsapp_client.py`
- [Messenger client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/messenger_client.py): `src/integrations/messenger_client.py`
- [Slack client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/slack_client.py): `src/integrations/slack_client.py`
- [HubSpot client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/hubspot_client.py): `src/integrations/hubspot_client.py`
- [GoHighLevel client](https://github.com/sohaggain/ai-omnichannel-support-agent/blob/main/src/integrations/gohighlevel_client.py): `src/integrations/gohighlevel_client.py`
- [n8n workflows](https://github.com/sohaggain/ai-omnichannel-support-agent/tree/main/workflows/n8n): `workflows/n8n`

### Other components

- **Customer**

## Connections

- Customer → FastAPI app: sends message
- FastAPI app → Website adapter: routes request
- FastAPI app → WhatsApp adapter: routes request
- FastAPI app → Email adapter: routes request
- FastAPI app → Messenger adapter: routes request
- Website adapter → Agent orchestrator: submits message
- WhatsApp adapter → Agent orchestrator: submits message
- Email adapter → Agent orchestrator: submits message
- Messenger adapter → Agent orchestrator: submits message
- Agent orchestrator → Anthropic Claude: requests completion
- Agent orchestrator → Agent tools: executes tools
- Agent tools → KB retrieval: searches knowledge
- KB ingestion → Vector store: upserts chunks
- KB retrieval → Vector store: queries chunks
- Agent orchestrator → CRM service: gets contact
- Agent orchestrator → DB sessions: persists conversation
- DB sessions → Support records: reads and writes
- CRM service → Support records: writes tickets
- CRM service → HubSpot client: mirrors ticket
- CRM service → GoHighLevel client: mirrors ticket
- HubSpot client → HubSpot: creates ticket
- GoHighLevel client → GoHighLevel: creates ticket
- Agent tools → Slack client: requests escalation
- Slack client → Slack: posts handoff
- WhatsApp client → WhatsApp API: sends reply
- Messenger client → Messenger API: sends reply
- Gmail client → Gmail API: sends reply
- n8n workflows → Slack: optional follow-up