Architecture

High-Level Flow

IndiaMART / Facebook / CSV
  -> lead_fetcher.py or streamlit_app.py
  -> leads table
  -> scheduler.py
  -> calls table row created
  -> LiveKit SIP participant created
  -> Vobiz dials the phone network
  -> lead answers the phone
  -> LiveKit room carries audio
  -> AI voice agent joins room
  -> qualification JSON saved
  -> talkingshops_pusher.py creates CRM task

Runtime Services

Service	Command	Responsibility
Agent	`python agent_realtime.py start` or `python agent.py start`	Joins LiveKit rooms and conducts calls
Scheduler	`python scheduler.py`	Finds eligible leads, creates call records, starts SIP calls, pushes CRM tasks
Lead fetcher	`python lead_fetcher.py`	Polls IndiaMART and receives Facebook webhooks
Dashboard	`streamlit run streamlit_app.py`	Shows leads/calls and imports CSV leads
Token server	`python token_server.py`	Issues LiveKit JWT tokens for local browser testing
Database	PostgreSQL	Stores leads, call attempts, durations, statuses, and qualification data

Call Room Contract

The scheduler creates one LiveKit room per lead:

ignitech-lead-{lead_id}

The SIP participant identity must be:

sip-lead-{lead_id}

The agents use this identity format to detect that the participant is a phone caller and to extract the lead ID.

Concurrency Control

The scheduler limits active outbound calls using:

MAX_CONCURRENT_CALLS=1

Active calls are rows in calls with status='calling'. Before starting more calls, the scheduler also fails stale calling rows older than:

STALE_CALL_MINUTES=5

This prevents stuck call records from permanently blocking the queue.

Calling Window

Calls only start when the local time is inside the configured window:

CALL_TIMEZONE=Asia/Kolkata
CALL_HOURS_START=9
CALL_HOURS_END=20
CALL_ALLOWED_WEEKDAYS=monday,tuesday,wednesday,thursday,friday,saturday

The end hour is exclusive. With the values above, calls can start from 09:00 through 19:59.

Deployment Shape

docker-compose.yml runs:

db: PostgreSQL 16
agent: defaults to python agent_realtime.py start
lead_fetcher: lead ingestion service
scheduler: call scheduler and CRM push loop
dashboard: Streamlit dashboard on container port 8501, bound to host 127.0.0.1:8502
web: token server

Getting Started

Integrations

Operations

Architecture

High-Level Flow

Runtime Services

Call Room Contract

Concurrency Control

Calling Window

Deployment Shape

​High-Level Flow

​Runtime Services

​Call Room Contract

​Concurrency Control

​Calling Window

​Deployment Shape

High-Level Flow

Runtime Services

Call Room Contract

Concurrency Control

Calling Window

Deployment Shape