High-Level Architecture
Vaani Dialer Architecture
Coming Soon — The Vaani Dialer is in development and available on the Dev instance for testing.
Dialer Pipeline
Component roles:
| Component | What It Does |
|---|
| Ticker | Emits CampaignTick events at the campaign’s dialer_interval (2–15 seconds) |
| Hopper | Fills the prospect queue — selects prospects based on list priority, timezone windows, DNC, and expiry rules |
| Dialer | Consumes tick events and originates outbound calls via the Vaani backend, respecting call ratio and damper controls |
| Scheduler | Handles scheduling requests — callback queuing, time-delayed prospects, and scheduling coordination |
Integration with Vaani Backend
The dialer connects to the main Vaani platform through:
- Campaign fields —
agent_id, workspace, email link each campaign to a Vaani agent and workspace
- REST API — The
v_views layer exposes campaign CRUD, prospect upload, and status endpoints consumed by the Vaani dashboard
- Cache invalidation — Campaign updates automatically clear Redis cache via
vaani_data_{slug} keys
Component Interaction Map
Frontend → Backend → Database
Phone Call → SIP → LiveKit → Agent Worker
Runtime Flows
Application Startup
Backend (FastAPI)
Agent Worker (LiveKit)
Celery Workers
gunicorn starts with Uvicorn workers → app/asgi.py → app/main.pylifespan() context manager initializes httpx.AsyncClient singleton- CORS middleware registered (all origins)
- 14 routers registered under their prefixes
- Health check at
GET /
livekit-agents CLI starts the worker process- Worker connects to LiveKit server via
LIVEKIT_URL
- Registers
entrypoint() as the job handler
- Waits for incoming room jobs (dispatch)
celery -A app.workers.celery_app.celery worker starts workercelery -A app.workers.celery_app.celery beat starts scheduler- Connects to Redis as broker/backend
- Processes batch dispatch tasks (
dispatch_batch)
Request Lifecycle (REST API)
Voice Call Lifecycle
Authentication & Authorization
Authentication Chain
Authorization (RBAC)
| Operation | Required Role |
|---|
| View data (calls, agents, reports) | member |
| Create/edit agents, SIP, campaigns | developer |
| Manage workspaces, invite members | admin |
| Platform administration | superuser (user flag) |
Data Storage Design
PostgreSQL (Primary Database)
| Table | Model | Expected Scale |
|---|
agents | Agents | Hundreds |
users | User | Thousands |
workspaces | Workspace | Hundreds |
user_workspaces | UserWorkspace | Thousands |
call_logs | CallLog | Millions |
logs (SIP) | SIP | Hundreds |
campaigns | Campaign | Hundreds |
batch_jobs | BatchJob | Thousands |
batch_items | BatchItem | Millions |
chat_logs | ChatLog | Hundreds of K |
Redis
livekit:active_calls — Integer counter of concurrent calls (TTL: 600s)- Celery task results and queue messages
AWS S3
- Pattern:
mv/{YYYY}/{MM}/{DD}/{call_log_id}.ogg
- Access: Pre-signed URLs (1-hour expiry)
External API Dependencies
| Service | Purpose | Config Keys |
|---|
| LiveKit | Real-time media, SIP gateway | LIVEKIT_API_KEY, LIVEKIT_API_SECRET, LIVEKIT_URL |
| OpenAI | LLM (GPT-4, GPT-4o), TTS, RAG | OPENAI_API_KEY |
| Groq | LLM (fast inference) | GROQ_API_KEY |
| Deepgram | STT (Nova-3), TTS | DEEPGRAM_API_KEY |
| ElevenLabs | TTS (high quality) | ELEVENLABS_API_KEY |
| Cartesia | STT, TTS | CARTESIA_API_KEY |
| Sarvam | STT, TTS (Indian languages) | SARVAM_API_KEY |
| Twilio | Phone provisioning, SIP trunking | TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN |
| Vonage | Phone provisioning, SIP trunking | VONAGE_API_KEY, VONAGE_API_SECRET |
| AWS S3 | Call recording storage | S3_BUCKET_NAME, S3_REGION, S3_ACCESS_KEY, S3_SECRET_KEY |
