Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.spn.wtf/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ServiceCommandResponsibility
Agentpython agent_realtime.py start or python agent.py startJoins LiveKit rooms and conducts calls
Schedulerpython scheduler.pyFinds eligible leads, creates call records, starts SIP calls, pushes CRM tasks
Lead fetcherpython lead_fetcher.pyPolls IndiaMART and receives Facebook webhooks
Dashboardstreamlit run streamlit_app.pyShows leads/calls and imports CSV leads
Token serverpython token_server.pyIssues LiveKit JWT tokens for local browser testing
DatabasePostgreSQLStores 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