# haroon-world/ai-agent-cloud architecture

> Architecture diagram of the GitHub repository haroon-world/ai-agent-cloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haroon-world/ai-agent-cloud
- Repository: https://github.com/haroon-world/ai-agent-cloud

## Overview

ClinicConnect AI is a multi-tenant clinic receptionist platform: patients ask questions and book or manage appointments through web chat or WhatsApp, while clinic staff can take over conversations and platform owners manage tenants and subscription requests. The graph separates channel entry points, AI processing, clinic operations, and administration. Edges are limited to relationships shown in the README, excerpts, or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`ai/agent.py`](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/agent.py) (Receptionist Agent), [`routes/whatsapp.py`](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/whatsapp.py) (WhatsApp Webhook), [`routes/admin.py`](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/admin.py) (Clinic Admin), [`app.py`](https://github.com/haroon-world/ai-agent-cloud/blob/main/app.py) (Application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_channels["Patient Channels"]
  node_web_chat["Web Chat<br/>[chat.py]"]
  node_whatsapp_route["WhatsApp Webhook<br/>[whatsapp.py]"]
  node_whatsapp_service["WhatsApp Messaging"]
end

subgraph group_ai["AI Receptionist"]
  node_agent["Receptionist Agent<br/>[agent.py]"]
  node_llm["LLM Providers<br/>[llm_client.py]"]
  node_prompts["Conversation Prompts<br/>[prompts.py]"]
  node_response["Response Generation"]
  node_tools["Agent Tools<br/>[tools.py]"]
  node_speech["Speech Processing<br/>[speech_client.py]"]
end

subgraph group_clinic["Clinic Operations"]
  node_booking["Booking &amp; Availability<br/>[booking_service.py]"]
  node_reminders["Appointment Reminders"]
  node_handoff["Human Handoff<br/>[handoff_service.py]"]
end

subgraph group_management["Administration"]
  node_admin_routes["Clinic Admin<br/>[admin.py]"]
  node_platform_routes["Platform Console<br/>[platform.py]"]
  node_subscriptions["Subscription Lifecycle"]
  node_email["Email Service<br/>[email_service.py]"]
end

subgraph group_data["Persistence &amp; Integrations"]
  node_records["Clinic &amp; Conversation Records<br/>[business.py]"]
  node_user_records["User Records<br/>[user.py]"]
  node_whatsapp_accounts["WhatsApp Accounts"]
  node_database[("SQL Database<br/>[__init__.py]")]
end

node_patient(("Patient"))
node_staff(("Clinic Staff"))
node_platform_owner(("Platform Owner"))
node_llm_provider{{"LLM Provider"}}
node_speech_provider{{"Speech Provider"}}
node_meta{{"Meta WhatsApp API"}}
node_app["Application<br/>[app.py]"]

node_patient -->|"uses"| node_web_chat
node_patient -->|"messages"| node_whatsapp_route
node_web_chat -->|"routes chat"| node_agent
node_whatsapp_route -->|"routes messages"| node_agent
node_web_chat -->|"transcribes audio"| node_speech
node_whatsapp_route -->|"transcribes audio"| node_speech
node_agent -->|"requests completions"| node_llm
node_agent -->|"uses prompts"| node_prompts
node_agent -->|"uses generator"| node_response
node_agent -->|"dispatches tools"| node_tools
node_llm -->|"uses tool definitions"| node_tools
node_tools -->|"calls booking"| node_booking
node_tools -->|"triggers handoff"| node_handoff
node_booking -->|"schedules reminders"| node_reminders
node_admin_routes -->|"uses booking services"| node_booking
node_admin_routes -->|"requests takeover"| node_handoff
node_staff -->|"manages clinic"| node_admin_routes
node_platform_owner -->|"manages tenants"| node_platform_routes
node_platform_routes -->|"manages requests"| node_subscriptions
node_platform_routes -->|"uses email service"| node_email
node_admin_routes -->|"checks access"| node_subscriptions
node_handoff -->|"sends staff replies"| node_whatsapp_service
node_whatsapp_route -->|"uses messaging service"| node_whatsapp_service
node_whatsapp_service -->|"sends API requests"| node_meta
node_llm -.->|"calls provider"| node_llm_provider
node_speech -.->|"uses configured provider"| node_speech_provider
node_agent -->|"reads conversation state"| node_records
node_booking -->|"reads and writes"| node_database
node_subscriptions -->|"updates subscription data"| node_database
node_whatsapp_route -->|"looks up account"| node_whatsapp_accounts
node_admin_routes -->|"queries users"| node_user_records
node_app -->|"registers route"| node_web_chat
node_app -->|"registers route"| node_whatsapp_route
node_app -->|"registers route"| node_admin_routes
node_app -->|"registers route"| node_platform_routes

click node_web_chat "https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/chat.py"
click node_whatsapp_route "https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/whatsapp.py"
click node_agent "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/agent.py"
click node_llm "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/llm_client.py"
click node_prompts "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/prompts.py"
click node_response "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/response_generator.py"
click node_tools "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/tools.py"
click node_speech "https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/speech_client.py"
click node_booking "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/booking_service.py"
click node_reminders "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/reminder_service.py"
click node_handoff "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/handoff_service.py"
click node_admin_routes "https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/admin.py"
click node_platform_routes "https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/platform.py"
click node_subscriptions "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/subscription_service.py"
click node_email "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/email_service.py"
click node_whatsapp_service "https://github.com/haroon-world/ai-agent-cloud/blob/main/services/whatsapp_service.py"
click node_records "https://github.com/haroon-world/ai-agent-cloud/blob/main/models/business.py"
click node_user_records "https://github.com/haroon-world/ai-agent-cloud/blob/main/models/user.py"
click node_whatsapp_accounts "https://github.com/haroon-world/ai-agent-cloud/blob/main/models/whatsapp_account.py"
click node_database "https://github.com/haroon-world/ai-agent-cloud/blob/main/models/__init__.py"
click node_app "https://github.com/haroon-world/ai-agent-cloud/blob/main/app.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_chat,node_whatsapp_route,node_whatsapp_service toneBlue
class node_agent,node_llm,node_prompts,node_response,node_tools,node_speech toneAmber
class node_booking,node_reminders,node_handoff,node_meta toneMint
class node_admin_routes,node_platform_routes,node_subscriptions,node_email toneRose
class node_records,node_user_records,node_whatsapp_accounts,node_database,node_patient,node_staff,node_platform_owner,node_llm_provider,node_speech_provider toneIndigo
class node_app toneTeal
```

## Components

### Patient Channels

- [Web Chat](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/chat.py): `routes/chat.py`
- [WhatsApp Webhook](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/whatsapp.py): `routes/whatsapp.py`
- [WhatsApp Messaging](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/whatsapp_service.py): `services/whatsapp_service.py`

### AI Receptionist

- [Receptionist Agent](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/agent.py): `ai/agent.py`
- [LLM Providers](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/llm_client.py): `ai/llm_client.py`
- [Conversation Prompts](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/prompts.py): `ai/prompts.py`
- [Response Generation](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/response_generator.py): `ai/response_generator.py`
- [Agent Tools](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/tools.py): `ai/tools.py`
- [Speech Processing](https://github.com/haroon-world/ai-agent-cloud/blob/main/ai/speech_client.py): `ai/speech_client.py`

### Clinic Operations

- [Booking & Availability](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/booking_service.py): `services/booking_service.py`
- [Appointment Reminders](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/reminder_service.py): `services/reminder_service.py`
- [Human Handoff](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/handoff_service.py): `services/handoff_service.py`

### Administration

- [Clinic Admin](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/admin.py): `routes/admin.py`
- [Platform Console](https://github.com/haroon-world/ai-agent-cloud/blob/main/routes/platform.py): `routes/platform.py`
- [Subscription Lifecycle](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/subscription_service.py): `services/subscription_service.py`
- [Email Service](https://github.com/haroon-world/ai-agent-cloud/blob/main/services/email_service.py): `services/email_service.py`

### Persistence & Integrations

- [Clinic & Conversation Records](https://github.com/haroon-world/ai-agent-cloud/blob/main/models/business.py): `models/business.py`
- [User Records](https://github.com/haroon-world/ai-agent-cloud/blob/main/models/user.py): `models/user.py`
- [WhatsApp Accounts](https://github.com/haroon-world/ai-agent-cloud/blob/main/models/whatsapp_account.py): `models/whatsapp_account.py`
- [SQL Database](https://github.com/haroon-world/ai-agent-cloud/blob/main/models/__init__.py): `models/__init__.py`

### Other components

- **Patient**
- **Clinic Staff**
- **Platform Owner**
- **LLM Provider**
- **Speech Provider**
- **Meta WhatsApp API**
- [Application](https://github.com/haroon-world/ai-agent-cloud/blob/main/app.py): `app.py`

## Connections

- Patient → Web Chat: uses (evidence: `README.md`)
- Patient → WhatsApp Webhook: messages (evidence: `README.md`)
- Web Chat → Receptionist Agent: routes chat (evidence: `routes/chat.py`)
- WhatsApp Webhook → Receptionist Agent: routes messages (evidence: `routes/whatsapp.py`)
- Web Chat → Speech Processing: transcribes audio (evidence: `routes/chat.py`)
- WhatsApp Webhook → Speech Processing: transcribes audio (evidence: `routes/whatsapp.py`)
- Receptionist Agent → LLM Providers: requests completions (evidence: `ai/agent.py`)
- Receptionist Agent → Conversation Prompts: uses prompts (evidence: `ai/agent.py`)
- Receptionist Agent → Response Generation: uses generator (evidence: `ai/agent.py`)
- Receptionist Agent → Agent Tools: dispatches tools (evidence: `ai/agent.py`)
- LLM Providers → Agent Tools: uses tool definitions (evidence: `ai/llm_client.py`)
- Agent Tools → Booking & Availability: calls booking (evidence: `ai/tools.py`)
- Agent Tools → Human Handoff: triggers handoff (evidence: `ai/tools.py`)
- Booking & Availability → Appointment Reminders: schedules reminders (evidence: `services/booking_service.py`)
- Clinic Admin → Booking & Availability: uses booking services (evidence: `routes/admin.py`)
- Clinic Admin → Human Handoff: requests takeover (evidence: `routes/admin.py`)
- Clinic Staff → Clinic Admin: manages clinic (evidence: `README.md`)
- Platform Owner → Platform Console: manages tenants (evidence: `README.md`)
- Platform Console → Subscription Lifecycle: manages requests (evidence: `routes/platform.py`)
- Platform Console → Email Service: uses email service (evidence: `routes/platform.py`)
- Clinic Admin → Subscription Lifecycle: checks access (evidence: `routes/admin.py`)
- Human Handoff → WhatsApp Messaging: sends staff replies (evidence: `services/handoff_service.py`)
- WhatsApp Webhook → WhatsApp Messaging: uses messaging service (evidence: `routes/whatsapp.py`)
- WhatsApp Messaging → Meta WhatsApp API: sends API requests (evidence: `services/whatsapp_service.py`)
- LLM Providers → LLM Provider: calls provider
- Speech Processing → Speech Provider: uses configured provider
- Receptionist Agent → Clinic & Conversation Records: reads conversation state (evidence: `ai/agent.py`)
- Booking & Availability → SQL Database: reads and writes (evidence: `services/booking_service.py`)
- Subscription Lifecycle → SQL Database: updates subscription data (evidence: `services/subscription_service.py`)
- WhatsApp Webhook → WhatsApp Accounts: looks up account (evidence: `routes/whatsapp.py`)
- Clinic Admin → User Records: queries users (evidence: `routes/admin.py`)
- Application → Web Chat: registers route (evidence: `app.py`)
- Application → WhatsApp Webhook: registers route (evidence: `app.py`)
- Application → Clinic Admin: registers route (evidence: `app.py`)
- Application → Platform Console: registers route (evidence: `app.py`)
