# 17rajsal/boloai architecture

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

- Interactive diagram: https://gitdiagram.com/17rajsal/boloai
- Repository: https://github.com/17rajsal/boloai

## Overview

BoloAI is a voice-first digital-services gateway: callers use an ordinary phone or the web interface, speak a request, and receive a concise spoken result. Its main call flow transcribes audio, reasons over session context, uses domain tools, verifies results, and speaks the response; confirmed actions can dispatch SMS or register grievances. A separate upload handoff analyzes submitted documents. The README documents several integrations and dashboard behaviors beyond the sampled implementation, so those links are shown as documented rather than independently verified in source.

Main entry points: [`app/agent/orchestrator.py`](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/orchestrator.py) (Agent orchestration), [`app/main.py`](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/main.py) (FastAPI backend), [`app/tools/registry.py`](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/registry.py) (Tool registry), [`app/services/verification.py`](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/verification.py) (Source verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Caller access"]
  node_exotel["Exotel PSTN"]
  node_api["FastAPI backend<br/>[main.py]"]
end

subgraph group_conversation["Voice conversation"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_orchestrator["Agent orchestration<br/>[orchestrator.py]"]
  node_memory["Session context<br/>[memory.py]"]
  node_prompt["Voice guidance<br/>[prompt.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
  node_telephony["Audio stream adapter<br/>[telephony.py]"]
end

subgraph group_assurance["Safety and verification"]
  node_safety["Safety guardrails<br/>[safety.py]"]
  node_verification["Source verification<br/>[verification.py]"]
  node_actions["Action lifecycle<br/>[actions.py]"]
end

subgraph group_services["Digital services"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_weather["Weather lookup<br/>[weather.py]"]
  node_schemes["Government schemes<br/>[schemes.py]"]
  node_courier["Courier tracking<br/>[courier.py]"]
  node_search["Web search<br/>[search.py]"]
  node_sms["SMS dispatch<br/>[sms.py]"]
  node_upload["Document handoff<br/>[upload.py]"]
  node_multimodal["Image analysis<br/>[multimodal.py]"]
end

subgraph group_experience["Dashboard and state"]
  node_store[("Session and events<br/>[store.py]")]
  node_dashboard["Live dashboard<br/>[app.js]"]
end

node_caller(("Phone caller"))
node_web_user(("Web user"))
node_weather_api["Open-Meteo"]
node_sarvam["Sarvam AI"]
node_openai["AI model provider"]
node_official_sources["Official web sources"]

node_caller -->|"calls"| node_exotel
node_exotel -->|"streams audio"| node_api
node_api -->|"handles stream"| node_telephony
node_api -->|"transcribes audio"| node_stt
node_stt -.->|"uses speech service"| node_sarvam
node_api -->|"submits utterance"| node_orchestrator
node_orchestrator -->|"uses context"| node_memory
node_orchestrator -->|"uses guidance"| node_prompt
node_orchestrator -->|"checks safety"| node_safety
node_orchestrator -->|"selects tools"| node_registry
node_orchestrator -->|"records session"| node_store
node_registry -->|"dispatches lookup"| node_weather
node_registry -->|"dispatches lookup"| node_schemes
node_registry -->|"dispatches tracking"| node_courier
node_registry -->|"dispatches search"| node_search
node_registry -->|"dispatches SMS"| node_sms
node_registry -->|"normalizes actions"| node_actions
node_orchestrator -->|"verifies results"| node_verification
node_verification -->|"checks claims"| node_official_sources
node_weather -->|"fetches forecast"| node_weather_api
node_orchestrator -.->|"requests reasoning"| node_openai
node_orchestrator -->|"synthesizes answer"| node_tts
node_tts -.->|"uses speech service"| node_sarvam
node_api -->|"accepts upload"| node_upload
node_upload -.->|"analyzes document"| node_multimodal
node_api -->|"verifies extracted claims"| node_verification
node_web_user -->|"uses interface"| node_dashboard
node_dashboard -.->|"uses backend"| node_api
node_api -->|"persists session events"| node_store
node_api -->|"returns spoken audio"| node_caller

click node_api "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/main.py"
click node_stt "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/stt.py"
click node_orchestrator "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/orchestrator.py"
click node_memory "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/memory.py"
click node_prompt "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/prompt.py"
click node_tts "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/tts.py"
click node_telephony "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/telephony.py"
click node_safety "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/safety.py"
click node_verification "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/verification.py"
click node_actions "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/actions.py"
click node_registry "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/registry.py"
click node_weather "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/weather.py"
click node_schemes "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/schemes.py"
click node_courier "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/courier.py"
click node_search "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/search.py"
click node_sms "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/sms.py"
click node_upload "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/upload.py"
click node_multimodal "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/multimodal.py"
click node_store "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/store.py"
click node_dashboard "https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/static/app.js"

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_exotel,node_api,node_web_user toneBlue
class node_stt,node_orchestrator,node_memory,node_prompt,node_tts,node_telephony toneAmber
class node_safety,node_verification,node_actions toneMint
class node_registry,node_weather,node_schemes,node_courier,node_search,node_sms,node_upload,node_multimodal toneRose
class node_store,node_dashboard,node_caller,node_weather_api,node_sarvam,node_openai,node_official_sources toneIndigo
```

## Components

### Caller access

- **Exotel PSTN**
- [FastAPI backend](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/main.py): `app/main.py`

### Voice conversation

- [Speech recognition](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/stt.py): `app/adapters/stt.py`
- [Agent orchestration](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/orchestrator.py): `app/agent/orchestrator.py`
- [Session context](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/memory.py): `app/agent/memory.py`
- [Voice guidance](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/agent/prompt.py): `app/agent/prompt.py`
- [Speech synthesis](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/tts.py): `app/adapters/tts.py`
- [Audio stream adapter](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/telephony.py): `app/adapters/telephony.py`

### Safety and verification

- [Safety guardrails](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/safety.py): `app/services/safety.py`
- [Source verification](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/verification.py): `app/services/verification.py`
- [Action lifecycle](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/actions.py): `app/services/actions.py`

### Digital services

- [Tool registry](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/registry.py): `app/tools/registry.py`
- [Weather lookup](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/weather.py): `app/tools/weather.py`
- [Government schemes](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/schemes.py): `app/tools/schemes.py`
- [Courier tracking](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/courier.py): `app/tools/courier.py`
- [Web search](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/search.py): `app/tools/search.py`
- [SMS dispatch](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/tools/sms.py): `app/tools/sms.py`
- [Document handoff](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/services/upload.py): `app/services/upload.py`
- [Image analysis](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/adapters/multimodal.py): `app/adapters/multimodal.py`

### Dashboard and state

- [Session and events](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/store.py): `app/store.py`
- [Live dashboard](https://github.com/17rajsal/boloai/blob/antigravity/final-demo/app/static/app.js): `app/static/app.js`

### Other components

- **Phone caller**
- **Web user**
- **Open-Meteo**
- **Sarvam AI**
- **AI model provider**
- **Official web sources**

## Connections

- Phone caller → Exotel PSTN: calls (evidence: `README.md`)
- Exotel PSTN → FastAPI backend: streams audio (evidence: `README.md`)
- FastAPI backend → Audio stream adapter: handles stream (evidence: `README.md`)
- FastAPI backend → Speech recognition: transcribes audio (evidence: `app/main.py`)
- Speech recognition → Sarvam AI: uses speech service (evidence: `README.md`)
- FastAPI backend → Agent orchestration: submits utterance (evidence: `app/main.py`)
- Agent orchestration → Session context: uses context (evidence: `app/agent/orchestrator.py`)
- Agent orchestration → Voice guidance: uses guidance (evidence: `app/agent/orchestrator.py`)
- Agent orchestration → Safety guardrails: checks safety (evidence: `app/agent/orchestrator.py`)
- Agent orchestration → Tool registry: selects tools (evidence: `app/agent/orchestrator.py`)
- Agent orchestration → Session and events: records session (evidence: `app/agent/orchestrator.py`)
- Tool registry → Weather lookup: dispatches lookup (evidence: `app/tools/registry.py`)
- Tool registry → Government schemes: dispatches lookup (evidence: `app/tools/registry.py`)
- Tool registry → Courier tracking: dispatches tracking (evidence: `app/tools/registry.py`)
- Tool registry → Web search: dispatches search (evidence: `app/tools/registry.py`)
- Tool registry → SMS dispatch: dispatches SMS (evidence: `app/tools/registry.py`)
- Tool registry → Action lifecycle: normalizes actions (evidence: `app/tools/registry.py`)
- Agent orchestration → Source verification: verifies results (evidence: `app/agent/orchestrator.py`)
- Source verification → Official web sources: checks claims (evidence: `README.md`)
- Weather lookup → Open-Meteo: fetches forecast (evidence: `README.md`)
- Agent orchestration → AI model provider: requests reasoning (evidence: `README.md`)
- Agent orchestration → Speech synthesis: synthesizes answer (evidence: `README.md`)
- Speech synthesis → Sarvam AI: uses speech service (evidence: `README.md`)
- FastAPI backend → Document handoff: accepts upload (evidence: `app/main.py`)
- Document handoff → Image analysis: analyzes document (evidence: `README.md`)
- FastAPI backend → Source verification: verifies extracted claims (evidence: `app/main.py`)
- Web user → Live dashboard: uses interface (evidence: `README.md`)
- Live dashboard → FastAPI backend: uses backend (evidence: `README.md`)
- FastAPI backend → Session and events: persists session events (evidence: `app/main.py`)
- FastAPI backend → Phone caller: returns spoken audio (evidence: `README.md`)
