# juspay/clairvoyance architecture

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

- Interactive diagram: https://gitdiagram.com/juspay/clairvoyance
- Repository: https://github.com/juspay/clairvoyance

## Overview

Clairvoyance is a FastAPI multi-agent conversational platform. A user request enters an API router, which delegates to Breeze Buddy call management; calls are dispatched into a workflow-driven voice agent that runs speech recognition, an LLM, and speech synthesis while integrating with telephony. The repository also contains text chat, commerce assistance, knowledge-base, analytics, and evaluation capabilities. Several subsystem relationships are documented in the README or visible in the source index; unsampled implementations are represented at their supported directory paths, and uncertain links are omitted.

Main entry points: [`app/api/routers/breeze_buddy/chat/handlers.py`](https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/chat/handlers.py) (Chat API), [`app/ai/voice/agents/breeze_buddy/agent`](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/agent) (Voice agent), [`app/main.py`](https://github.com/juspay/clairvoyance/blob/release/app/main.py) (FastAPI app), [`app/api/routers/breeze_buddy`](https://github.com/juspay/clairvoyance/tree/release/app/api/routers/breeze_buddy) (Breeze Buddy API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_bb_router["Breeze Buddy API"]
  node_call_manager["Call manager<br/>[calls.py]"]
  node_dispatch["Call dispatch"]
end

subgraph group_voice["Voice workflows"]
  node_voice_agent["Voice agent"]
  node_voice_pipeline["Speech pipeline<br/>[pipeline.py]"]
  node_telephony["Telephony providers"]
  node_speech_services["STT / LLM / TTS"]
  node_template_engine["Workflow templates"]
  node_dragon_tts["DragonTTS cache<br/>[service.py]"]
end

subgraph group_conversation["Chat and commerce"]
  node_chat_api["Chat API<br/>[handlers.py]"]
  node_chat_turn["Chat turn engine<br/>[turn_core.py]"]
  node_commerce_assist["Commerce assistance"]
  node_widget_api["Commerce widget<br/>[handlers.py]"]
end

subgraph group_platform["Knowledge and evaluation"]
  node_knowledge["Knowledge base"]
  node_analytics["Analytics API<br/>[handlers.py]"]
  node_evaluations["Conversation evaluation"]
end

subgraph group_persistence["State and infrastructure"]
  node_chat_sessions[("Chat session store<br/>[chat_session.py]")]
  node_redis[("Redis<br/>[client.py]")]
end

node_caller(("API caller"))
node_telephony_service(("Telephony network"))
node_client(("Chat / widget user"))

node_caller -->|"requests"| node_fastapi
node_fastapi -->|"initializes routes"| node_bb_router
node_bb_router -->|"delegates calls"| node_call_manager
node_call_manager -->|"dispatches calls"| node_dispatch
node_call_manager -->|"launches agent"| node_voice_agent
node_voice_agent -->|"builds pipeline"| node_voice_pipeline
node_voice_pipeline -->|"uses speech services"| node_speech_services
node_voice_agent -->|"manages calls"| node_telephony
node_telephony -->|"connects calls"| node_telephony_service
node_voice_agent -.->|"runs workflows"| node_template_engine
node_client -->|"sends messages"| node_chat_api
node_chat_api -->|"invokes turns"| node_chat_turn
node_chat_api -->|"reads and writes"| node_chat_sessions
node_chat_api -->|"locks sessions"| node_redis
node_client -->|"uses widget"| node_widget_api
node_widget_api -->|"invokes turns"| node_chat_turn
node_widget_api -->|"uses commerce policy"| node_commerce_assist
node_chat_api -->|"queues analysis"| node_knowledge
node_bb_router -.->|"serves analytics"| node_analytics
node_fastapi -.->|"starts evaluation services"| node_evaluations
node_speech_services -.->|"synthesizes via proxy"| node_dragon_tts

click node_fastapi "https://github.com/juspay/clairvoyance/blob/release/app/main.py"
click node_bb_router "https://github.com/juspay/clairvoyance/tree/release/app/api/routers/breeze_buddy"
click node_call_manager "https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/managers/calls.py"
click node_dispatch "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/dispatch"
click node_voice_agent "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/agent"
click node_voice_pipeline "https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/agent/pipeline.py"
click node_telephony "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/services/telephony"
click node_speech_services "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice"
click node_chat_api "https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/chat/handlers.py"
click node_chat_turn "https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/chat/turn_core.py"
click node_commerce_assist "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/assist/commerce"
click node_widget_api "https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/widget/handlers.py"
click node_knowledge "https://github.com/juspay/clairvoyance/tree/release/app/services/knowledge_base"
click node_analytics "https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/analytics/handlers.py"
click node_evaluations "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/services/evals"
click node_chat_sessions "https://github.com/juspay/clairvoyance/blob/release/app/database/accessor/breeze_buddy/chat_session.py"
click node_redis "https://github.com/juspay/clairvoyance/blob/release/app/services/redis/client.py"
click node_template_engine "https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/template"
click node_dragon_tts "https://github.com/juspay/clairvoyance/blob/release/dragontts/app/cache/service.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_fastapi,node_bb_router,node_call_manager,node_dispatch,node_client toneBlue
class node_voice_agent,node_voice_pipeline,node_telephony,node_speech_services,node_template_engine,node_dragon_tts toneAmber
class node_chat_api,node_chat_turn,node_commerce_assist,node_widget_api,node_caller toneMint
class node_knowledge,node_analytics,node_evaluations toneRose
class node_chat_sessions,node_redis,node_telephony_service toneIndigo
```

## Components

### API and orchestration

- [FastAPI app](https://github.com/juspay/clairvoyance/blob/release/app/main.py): `app/main.py`
- [Breeze Buddy API](https://github.com/juspay/clairvoyance/tree/release/app/api/routers/breeze_buddy): `app/api/routers/breeze_buddy`
- [Call manager](https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/managers/calls.py): `app/ai/voice/agents/breeze_buddy/managers/calls.py`
- [Call dispatch](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/dispatch): `app/ai/voice/agents/breeze_buddy/dispatch`

### Voice workflows

- [Voice agent](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/agent): `app/ai/voice/agents/breeze_buddy/agent`
- [Speech pipeline](https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/agent/pipeline.py): `app/ai/voice/agents/breeze_buddy/agent/pipeline.py`
- [Telephony providers](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/services/telephony): `app/ai/voice/agents/breeze_buddy/services/telephony`
- [STT / LLM / TTS](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice): `app/ai/voice`
- [Workflow templates](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/template): `app/ai/voice/agents/breeze_buddy/template`
- [DragonTTS cache](https://github.com/juspay/clairvoyance/blob/release/dragontts/app/cache/service.py): `dragontts/app/cache/service.py`

### Chat and commerce

- [Chat API](https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/chat/handlers.py): `app/api/routers/breeze_buddy/chat/handlers.py`
- [Chat turn engine](https://github.com/juspay/clairvoyance/blob/release/app/ai/voice/agents/breeze_buddy/chat/turn_core.py): `app/ai/voice/agents/breeze_buddy/chat/turn_core.py`
- [Commerce assistance](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/assist/commerce): `app/ai/voice/agents/breeze_buddy/assist/commerce`
- [Commerce widget](https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/widget/handlers.py): `app/api/routers/breeze_buddy/widget/handlers.py`

### Knowledge and evaluation

- [Knowledge base](https://github.com/juspay/clairvoyance/tree/release/app/services/knowledge_base): `app/services/knowledge_base`
- [Analytics API](https://github.com/juspay/clairvoyance/blob/release/app/api/routers/breeze_buddy/analytics/handlers.py): `app/api/routers/breeze_buddy/analytics/handlers.py`
- [Conversation evaluation](https://github.com/juspay/clairvoyance/tree/release/app/ai/voice/agents/breeze_buddy/services/evals): `app/ai/voice/agents/breeze_buddy/services/evals`

### State and infrastructure

- [Chat session store](https://github.com/juspay/clairvoyance/blob/release/app/database/accessor/breeze_buddy/chat_session.py): `app/database/accessor/breeze_buddy/chat_session.py`
- [Redis](https://github.com/juspay/clairvoyance/blob/release/app/services/redis/client.py): `app/services/redis/client.py`

### Other components

- **API caller**
- **Telephony network**
- **Chat / widget user**

## Connections

- API caller → FastAPI app: requests (evidence: `README.md`)
- FastAPI app → Breeze Buddy API: initializes routes (evidence: `README.md`)
- Breeze Buddy API → Call manager: delegates calls (evidence: `README.md`)
- Call manager → Call dispatch: dispatches calls (evidence: `app/ai/voice/agents/breeze_buddy/dispatch/v2/routes.py`)
- Call manager → Voice agent: launches agent (evidence: `README.md`)
- Voice agent → Speech pipeline: builds pipeline (evidence: `app/ai/voice/agents/breeze_buddy/agent/pipeline.py`)
- Speech pipeline → STT / LLM / TTS: uses speech services (evidence: `app/ai/voice/agents/breeze_buddy/agent/pipeline.py`)
- Voice agent → Telephony providers: manages calls (evidence: `README.md`)
- Telephony providers → Telephony network: connects calls (evidence: `README.md`)
- Voice agent → Workflow templates: runs workflows (evidence: `app/ai/voice/agents/breeze_buddy/agent/pipeline.py`)
- Chat / widget user → Chat API: sends messages (evidence: `README.md`)
- Chat API → Chat turn engine: invokes turns (evidence: `app/api/routers/breeze_buddy/chat/handlers.py`)
- Chat API → Chat session store: reads and writes (evidence: `app/api/routers/breeze_buddy/chat/handlers.py`)
- Chat API → Redis: locks sessions (evidence: `app/api/routers/breeze_buddy/chat/handlers.py`)
- Chat / widget user → Commerce widget: uses widget (evidence: `README.md`)
- Commerce widget → Chat turn engine: invokes turns (evidence: `app/api/routers/breeze_buddy/widget/handlers.py`)
- Commerce widget → Commerce assistance: uses commerce policy (evidence: `app/api/routers/breeze_buddy/widget/handlers.py`)
- Chat API → Knowledge base: queues analysis (evidence: `app/api/routers/breeze_buddy/chat/handlers.py`)
- Breeze Buddy API → Analytics API: serves analytics (evidence: `app/api/routers/breeze_buddy/analytics/handlers.py`)
- FastAPI app → Conversation evaluation: starts evaluation services (evidence: `app/main.py`)
- STT / LLM / TTS → DragonTTS cache: synthesizes via proxy
