# revolutionarybukhari/ai-calling-agent architecture

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

- Interactive diagram: https://gitdiagram.com/revolutionarybukhari/ai-calling-agent
- Repository: https://github.com/revolutionarybukhari/ai-calling-agent

## Overview

This is a Flask-based AI calling agent for inbound and outbound mental-health conversations. The documented voice loop is: a caller reaches Twilio, Flask routes call events, speech is transcribed by Twilio and submitted to the chatbot, the response is synthesized to audio, and Twilio plays it while gathering the next utterance. Persistent chat history and appointment operations form a supporting data branch. README claims Pinecone and STT capabilities, but no implementation for Pinecone or independent STT appears in the supplied tree/excerpts; speech capture is represented by Twilio Gather. Edges are limited to visible calls or README-documented capabilities.

Main entry points: [`app.py`](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/app.py) (Speech Capture), [`modules/chatbot.py`](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/chatbot.py) (Chat Responses), [`modules/twilio_api.py`](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/twilio_api.py) (Twilio Call Handling), [`modules/agent_tools.py`](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/agent_tools.py) (History and Booking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calling["Call Control"]
  node_flask["Flask API<br/>[app.py]"]
  node_twilio_flow["Twilio Call Handling<br/>[twilio_api.py]"]
  node_speech_capture["Speech Capture<br/>[app.py]"]
  node_twilio["Twilio"]
  node_whatsapp_sender["WhatsApp Sender<br/>[sender.py]"]
end

subgraph group_conversation["Conversation"]
  node_chat["Chat Responses<br/>[chatbot.py]"]
  node_agent["Agent Responses<br/>[chatbot.py]"]
  node_openai["OpenAI"]
  node_pinecone[("Pinecone")]
end

subgraph group_persistence["Persistence"]
  node_agent_tools["History and Booking<br/>[agent_tools.py]"]
  node_mongo[("MongoDB Records<br/>[mongodb.py]")]
end

subgraph group_speech["Speech Output"]
  node_tts["Audio Synthesis<br/>[tts.py]"]
  node_elevenlabs["ElevenLabs"]
end

node_caller(("Caller"))

node_caller -->|"sends call request"| node_flask
node_flask -->|"routes inbound call"| node_twilio_flow
node_flask -->|"handles speech post"| node_speech_capture
node_twilio_flow -->|"checks caller history"| node_mongo
node_twilio_flow -->|"starts outbound call"| node_twilio
node_twilio -->|"posts recognized speech"| node_speech_capture
node_speech_capture -->|"requests reply"| node_chat
node_chat -->|"generates response"| node_openai
node_speech_capture -->|"synthesizes reply"| node_tts
node_tts -->|"requests audio"| node_elevenlabs
node_speech_capture -->|"returns playback instructions"| node_twilio
node_agent -->|"loads and saves history"| node_agent_tools
node_agent_tools -->|"reads and writes records"| node_mongo
node_chat -.->|"alternate response path"| node_agent
node_chat -.->|"queries vectors"| node_pinecone
node_caller -.->|"receives WhatsApp message"| node_whatsapp_sender

click node_flask "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/app.py"
click node_twilio_flow "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/twilio_api.py"
click node_speech_capture "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/app.py"
click node_chat "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/chatbot.py"
click node_agent "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/chatbot.py"
click node_agent_tools "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/agent_tools.py"
click node_mongo "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/mongodb.py"
click node_tts "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/tts.py"
click node_whatsapp_sender "https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/sender.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_flask,node_twilio_flow,node_speech_capture,node_twilio,node_whatsapp_sender toneBlue
class node_chat,node_agent,node_openai,node_pinecone toneAmber
class node_agent_tools,node_mongo toneMint
class node_tts,node_elevenlabs toneRose
class node_caller toneIndigo
```

## Components

### Call Control

- [Flask API](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/app.py): `app.py`
- [Twilio Call Handling](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/twilio_api.py): `modules/twilio_api.py`
- [Speech Capture](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/app.py): `app.py`
- **Twilio**
- [WhatsApp Sender](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/sender.py): `modules/sender.py`

### Conversation

- [Chat Responses](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/chatbot.py): `modules/chatbot.py`
- [Agent Responses](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/chatbot.py): `modules/chatbot.py`
- **OpenAI**
- **Pinecone**

### Persistence

- [History and Booking](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/agent_tools.py): `modules/agent_tools.py`
- [MongoDB Records](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/mongodb.py): `modules/mongodb.py`

### Speech Output

- [Audio Synthesis](https://github.com/revolutionarybukhari/ai-calling-agent/blob/main/modules/tts.py): `modules/tts.py`
- **ElevenLabs**

### Other components

- **Caller**

## Connections

- Caller → Flask API: sends call request (evidence: `README.md`)
- Flask API → Twilio Call Handling: routes inbound call (evidence: `app.py`)
- Flask API → Speech Capture: handles speech post (evidence: `app.py`)
- Twilio Call Handling → MongoDB Records: checks caller history (evidence: `modules/twilio_api.py`)
- Twilio Call Handling → Twilio: starts outbound call (evidence: `modules/twilio_api.py`)
- Twilio → Speech Capture: posts recognized speech (evidence: `app.py`)
- Speech Capture → Chat Responses: requests reply (evidence: `app.py`)
- Chat Responses → OpenAI: generates response (evidence: `modules/chatbot.py`)
- Speech Capture → Audio Synthesis: synthesizes reply (evidence: `app.py`)
- Audio Synthesis → ElevenLabs: requests audio (evidence: `modules/tts.py`)
- Speech Capture → Twilio: returns playback instructions (evidence: `app.py`)
- Agent Responses → History and Booking: loads and saves history (evidence: `modules/chatbot.py`)
- History and Booking → MongoDB Records: reads and writes records (evidence: `modules/agent_tools.py`)
- Chat Responses → Agent Responses: alternate response path (evidence: `modules/chatbot.py`)
- Chat Responses → Pinecone: queries vectors
- Caller → WhatsApp Sender: receives WhatsApp message
