How sorrowsfr/spx-voice works
SPX Voice lets an operator build and publish a voice-agent workflow, configure models and telephony, then test it in-browser or deploy it to calls. The dashboard edits workflows and calls the FastAPI backend; backend execution creates an audio pipeline that runs workflow nodes and connects to realtime or traditional speech services. Telephony, campaigns, knowledge bases, recordings, and reporting extend that core. Paths and links for runtime components reflect the tree, README, and sampled excerpts; unsampled subsystem wiring is shown only where documented at a high level.
Main entry points: run_pipeline.py Run orchestration · workflow.py FastAPI routes · pipecat_engine.py Workflow engine · page.tsx Dashboard
Components 22
Agent authoring
- Dashboard
ui/src/app/workflow/[workflowId]/page.tsx - Workflow editor
ui/src/app/workflow/[workflowId]/RenderWorkflow.tsx - Workflow state
ui/src/app/workflow/[workflowId]/stores/workflowStore.ts
Backend services
- FastAPI routes
api/routes/workflow.py - Authentication
api/services/auth/depends.py - Workflow graph
api/services/workflow/workflow_graph.py - Model configuration
api/services/configuration/resolve.py - Campaign dispatch
api/services/campaign/campaign_orchestrator.py - Knowledge retrieval
api/services/workflow/tools/knowledge_base.py
Conversation runtime
- Run orchestration
api/services/pipecat/run_pipeline.py - Workflow engine
api/services/workflow/pipecat_engine.py - Audio pipeline
api/services/pipecat/pipeline_builder.py
External integrations
- Telephony providers
api/services/telephony/registry.py - LiveKit runtime
api/services/livekit/worker.py - Speech and model services
api/services/pipecat/service_factory.py
Persistence and jobs
- Database clients
api/db/db_client.py - Object storage
api/services/storage.py - Background tasks
api/tasks/arq.py
Other components
- Operator
- Caller / browser tester
- Model providers
- Telephony network
Connections 26
- Operator → Dashboard: uses
- Dashboard → Workflow editor: opens editor
- Workflow editor → Workflow state: updates state
- Dashboard → FastAPI routes: API requests
- FastAPI routes → Authentication: checks access
- FastAPI routes → Database clients: reads and writes
- FastAPI routes → Workflow graph: loads workflow
- FastAPI routes → Run orchestration: starts run
- Campaign dispatch → Run orchestration: dispatches run
- Run orchestration → Database clients: loads run data
- Run orchestration → Model configuration: resolves config
- Run orchestration → Workflow graph: uses graph
- Run orchestration → Audio pipeline: builds pipeline
- Run orchestration → Workflow engine: creates engine
- Audio pipeline → Workflow engine: dispatches frames
- Workflow engine → Knowledge retrieval: retrieves chunks
- Workflow engine → Database clients: updates run state
- Model configuration → Speech and model services: selects services
- Speech and model services → Model providers: calls models
- Run orchestration → LiveKit runtime: starts runtime
- Telephony providers → Telephony network: handles calls
- Telephony network → Telephony providers: sends callbacks
- Caller / browser tester → Telephony providers: places call
- Caller / browser tester → Run orchestration: starts browser test
- FastAPI routes → Object storage: stores media
- FastAPI routes → Background tasks: queues tasks