# takiuddinahmed/ai-call-support-agent architecture

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

- Interactive diagram: https://gitdiagram.com/takiuddinahmed/ai-call-support-agent
- Repository: https://github.com/takiuddinahmed/ai-call-support-agent

## Overview

Support agent is a local customer-support product for Robo Parts BD, with text chat and English voice calls sharing the same agent core. Customers discover products, check orders, and place cash-on-delivery orders; order placement is guarded by a quoted summary and explicit confirmation. Voice adds browser and Asterisk/SIP entry points, speech processing, and call diagnostics. The graph reflects the README and shown source/index references; some voice internals are unsampled, so uncertain links are omitted.

Main entry points: [`src/support_agent/loop.py`](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/loop.py) (Turn orchestrator), [`src/support_agent/voice/routes.py`](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/routes.py) (Voice routes), [`src/support_agent/server/app.py`](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/server/app.py) (HTTP application), [`src/support_agent/voice/pipeline.py`](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/pipeline.py) (Speech pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_browser["Chat and voice pages"]
  node_server["HTTP application<br/>[app.py]"]
end

subgraph group_agent["Conversation core"]
  node_session["Session state<br/>[session.py]"]
  node_instructions["Agent instructions<br/>[instructions.py]"]
  node_history["Prompt history<br/>[history.py]"]
  node_turn["Turn orchestrator<br/>[loop.py]"]
end

subgraph group_commerce["Store operations"]
  node_tools["Store tools and guards<br/>[tools.py]"]
  node_storeclient["Store API client<br/>[client.py]"]
  node_storemodels["Store data types<br/>[models.py]"]
end

subgraph group_voice["Voice calling"]
  node_voice_routes["Voice routes<br/>[routes.py]"]
  node_voice_deps["Voice dependencies<br/>[deps.py]"]
  node_voice_pipeline["Speech pipeline<br/>[pipeline.py]"]
  node_voice_agent["Voice agent processor<br/>[agent_processor.py]"]
  node_asterisk["Asterisk adapter<br/>[asterisk.py]"]
  node_debug["Call debug events<br/>[debug_hub.py]"]
end

subgraph group_runtime["Runtime services"]
  node_llm["Model client<br/>[llm.py]"]
  node_config["Settings<br/>[config.py]"]
end

node_customer(("Customer"))
node_store[("Robo Parts BD store")]
node_ollama[("Local Ollama")]
node_speech["Whisper and Kokoro"]
node_sip(("SIP softphone"))

node_customer -->|"uses"| node_browser
node_browser -->|"sends requests"| node_server
node_server -->|"creates and updates"| node_session
node_server -->|"authenticates with"| node_storeclient
node_server -->|"starts chat turn"| node_turn
node_turn -->|"builds prompt"| node_instructions
node_turn -->|"fits history"| node_history
node_turn -->|"streams model calls"| node_llm
node_turn -->|"dispatches tools"| node_tools
node_tools -->|"requests store data"| node_storeclient
node_storeclient -->|"calls store API"| node_store
node_storeclient -->|"maps responses"| node_storemodels
node_tools -->|"checks order approval"| node_session
node_config -->|"configures endpoint"| node_llm
node_server -->|"registers voice routes"| node_voice_routes
node_voice_routes -->|"builds call pipeline"| node_voice_pipeline
node_voice_routes -->|"uses dependencies"| node_voice_deps
node_voice_routes -->|"handles phone transport"| node_asterisk
node_voice_pipeline -->|"runs agent processor"| node_voice_agent
node_voice_agent -->|"shares agent core"| node_turn
node_voice_agent -->|"uses conversation state"| node_session
node_voice_pipeline -->|"transcribes and speaks"| node_speech
node_voice_deps -->|"warms model"| node_llm
node_voice_pipeline -->|"publishes events"| node_debug
node_sip -->|"places SIP call"| node_asterisk
node_asterisk -->|"opens phone route"| node_voice_routes
node_llm -->|"streams completions"| node_ollama
node_voice_routes -->|"serves call events"| node_debug

click node_browser "https://github.com/takiuddinahmed/ai-call-support-agent/tree/main/src/support_agent/server/static"
click node_server "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/server/app.py"
click node_session "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/session.py"
click node_instructions "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/instructions.py"
click node_history "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/history.py"
click node_turn "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/loop.py"
click node_llm "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/llm.py"
click node_config "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/config.py"
click node_tools "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/tools.py"
click node_storeclient "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/store/client.py"
click node_storemodels "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/store/models.py"
click node_voice_routes "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/routes.py"
click node_voice_deps "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/deps.py"
click node_voice_pipeline "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/pipeline.py"
click node_voice_agent "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/agent_processor.py"
click node_asterisk "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/asterisk.py"
click node_debug "https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/debug_hub.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_browser,node_server toneBlue
class node_session,node_instructions,node_history,node_turn,node_store,node_ollama toneAmber
class node_tools,node_storeclient,node_storemodels toneMint
class node_voice_routes,node_voice_deps,node_voice_pipeline,node_voice_agent,node_asterisk,node_debug toneRose
class node_llm,node_config,node_customer,node_speech,node_sip toneIndigo
```

## Components

### User interfaces

- [Chat and voice pages](https://github.com/takiuddinahmed/ai-call-support-agent/tree/main/src/support_agent/server/static): `src/support_agent/server/static`
- [HTTP application](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/server/app.py): `src/support_agent/server/app.py`

### Conversation core

- [Session state](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/session.py): `src/support_agent/session.py`
- [Agent instructions](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/instructions.py): `src/support_agent/instructions.py`
- [Prompt history](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/history.py): `src/support_agent/history.py`
- [Turn orchestrator](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/loop.py): `src/support_agent/loop.py`

### Store operations

- [Store tools and guards](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/tools.py): `src/support_agent/tools.py`
- [Store API client](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/store/client.py): `src/support_agent/store/client.py`
- [Store data types](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/store/models.py): `src/support_agent/store/models.py`

### Voice calling

- [Voice routes](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/routes.py): `src/support_agent/voice/routes.py`
- [Voice dependencies](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/deps.py): `src/support_agent/voice/deps.py`
- [Speech pipeline](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/pipeline.py): `src/support_agent/voice/pipeline.py`
- [Voice agent processor](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/agent_processor.py): `src/support_agent/voice/agent_processor.py`
- [Asterisk adapter](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/asterisk.py): `src/support_agent/voice/asterisk.py`
- [Call debug events](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/voice/debug_hub.py): `src/support_agent/voice/debug_hub.py`

### Runtime services

- [Model client](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/llm.py): `src/support_agent/llm.py`
- [Settings](https://github.com/takiuddinahmed/ai-call-support-agent/blob/main/src/support_agent/config.py): `src/support_agent/config.py`

### Other components

- **Customer**
- **Robo Parts BD store**
- **Local Ollama**
- **Whisper and Kokoro**
- **SIP softphone**

## Connections

- Customer → Chat and voice pages: uses (evidence: `README.md`)
- Chat and voice pages → HTTP application: sends requests (evidence: `src/support_agent/server/app.py`)
- HTTP application → Session state: creates and updates (evidence: `src/support_agent/server/app.py`)
- HTTP application → Store API client: authenticates with (evidence: `src/support_agent/server/app.py`)
- HTTP application → Turn orchestrator: starts chat turn (evidence: `src/support_agent/server/app.py`)
- Turn orchestrator → Agent instructions: builds prompt (evidence: `src/support_agent/loop.py`)
- Turn orchestrator → Prompt history: fits history (evidence: `src/support_agent/loop.py`)
- Turn orchestrator → Model client: streams model calls (evidence: `src/support_agent/loop.py`)
- Turn orchestrator → Store tools and guards: dispatches tools (evidence: `src/support_agent/loop.py`)
- Store tools and guards → Store API client: requests store data (evidence: `src/support_agent/tools.py`)
- Store API client → Robo Parts BD store: calls store API (evidence: `README.md`)
- Store API client → Store data types: maps responses (evidence: `src/support_agent/store/client.py`)
- Store tools and guards → Session state: checks order approval (evidence: `src/support_agent/tools.py`)
- Settings → Model client: configures endpoint (evidence: `src/support_agent/llm.py`)
- HTTP application → Voice routes: registers voice routes (evidence: `src/support_agent/server/app.py`)
- Voice routes → Speech pipeline: builds call pipeline (evidence: `src/support_agent/voice/routes.py`)
- Voice routes → Voice dependencies: uses dependencies (evidence: `src/support_agent/voice/routes.py`)
- Voice routes → Asterisk adapter: handles phone transport (evidence: `src/support_agent/voice/routes.py`)
- Speech pipeline → Voice agent processor: runs agent processor (evidence: `src/support_agent/voice/pipeline.py`)
- Voice agent processor → Turn orchestrator: shares agent core (evidence: `src/support_agent/voice/agent_processor.py`)
- Voice agent processor → Session state: uses conversation state (evidence: `src/support_agent/voice/agent_processor.py`)
- Speech pipeline → Whisper and Kokoro: transcribes and speaks (evidence: `README.md`)
- Voice dependencies → Model client: warms model (evidence: `src/support_agent/voice/deps.py`)
- Speech pipeline → Call debug events: publishes events (evidence: `src/support_agent/voice/pipeline.py`)
- SIP softphone → Asterisk adapter: places SIP call (evidence: `README.md`)
- Asterisk adapter → Voice routes: opens phone route (evidence: `README.md`)
- Model client → Local Ollama: streams completions (evidence: `src/support_agent/llm.py`)
- Voice routes → Call debug events: serves call events (evidence: `src/support_agent/voice/routes.py`)
