| System | Responsibility |
|---|---|
| VoxBridge | Auth, bots, campaigns, calls, CRM integrations, settings, recordings, API keys, fleet routing |
| VoxCore | Live media execution: STT, LLM, TTS, tools, transfer, recordings, post-call packaging |
| VoxUI | Admin and operator interface on top of VoxBridge APIs |
| VoxDialler | Campaign pacing, SIP dial attempts, AMD screening, and attach orchestration |
Runtime Role
VoxBridge does not run the live audio pipeline. It prepares the information needed for the call and stores the result after VoxCore finishes.What It Owns
| Area | What VoxBridge owns |
|---|---|
| Auth and users | JWT login, roles, admin users, agent/supervisor access boundaries |
| Bot config | Bot CRUD, prompts, policy config, provider config, tools, transfer settings, RAG attachment |
| Runtime config | /api/v1/config/{bot_id} response consumed by VoxCore at call start |
| Calls | Call records, transcripts, events, analysis, QC, stable recording access URLs |
| Campaigns | Campaign CRUD, CSV ingestion, number pools, retry settings, attempt reports |
| Fleet routing | Health-checks VoxCore fleet servers and picks available capacity for direct dialout |
| Carriers and SIP | LiveKit trunk mapping, DID lookup, outbound trunk selection |
| CRM integrations | API-key dialout, CRM pre-fetch, post-call push, variable mapping |
| Knowledge base | Document upload, chunking, embeddings, Qdrant search, bot attachment |
| Agent Desk | Queue state, timeout policy, handoff records, agent/supervisor APIs |
Important Modules
| File | Why it matters |
|---|---|
src/voxbridge/app.py | FastAPI app, startup checks, Mongo/Redis startup, route registration, trunk health loop |
src/voxbridge/settings.py | Environment settings for MongoDB, Redis, JWT, VoxCore, LiveKit, storage, Agent Desk |
src/voxbridge/routes/config.py | Runtime config endpoint called by VoxCore |
src/voxbridge/services/config_service.py | Builds the call-time config contract from stored bot/settings data |
src/voxbridge/routes/results.py | Receives final call results from VoxCore |
src/voxbridge/services/call_service.py | Stores call results and sends CRM post-call payloads |
src/voxbridge/routes/sip.py | CRM/admin dialout endpoint and SIP lookup helpers |
src/voxbridge/services/fleet_service.py | Fleet health checks and best-server selection |
src/voxbridge/routes/campaigns.py | Campaign creation, lifecycle actions, upload, reporting |
src/voxbridge/services/knowledge_* | Knowledge-base ingestion, embedding, Qdrant search |
src/voxbridge/routes/api_keys.py | CRM API key management |
src/voxbridge/routes/agent_desk.py | Agent Desk queue and handoff APIs |
API Boundaries
VoxBridge exposes three broad kinds of API:| API type | Used by | Purpose |
|---|---|---|
| Admin APIs | VoxUI | Bots, calls, campaigns, settings, users, carriers, knowledge bases |
| Internal APIs | VoxCore / VoxDialler | Runtime config, SIP lookup, call result delivery, fleet checks |
| External APIs | CRMs | API-key dialout and post-call webhooks |
X-VoxCore-Secret. CRM-triggered dialout uses X-API-Key so external systems do not need admin JWTs.
Data Stores
| Store | Use |
|---|---|
| MongoDB | Durable source of truth for users, bots, calls, campaigns, settings, API keys, KB metadata |
| Redis | Runtime cache and Agent Desk state/listener support |
| Qdrant | Knowledge-base vector search |
| S3 / MinIO / Spaces | Call recordings and uploaded assets, depending on deployment |
Operational Checks
When debugging VoxBridge, start with the surface that owns the failing state:| Symptom | First place to check |
|---|---|
| VoxCore cannot fetch config | Bot status, active hours, routes/config.py, services/config_service.py |
| Direct dialout picks the wrong worker | voxcore_fleet settings and services/fleet_service.py |
| Campaign rows do not progress | Campaign status, dialler health, campaign_calls indexes, VoxDialler logs |
| Call result missing | VoxCore result outbox, routes/results.py, call storage logs |
| CRM did not receive result | Integration config, services/call_service.py, post-call push logs |
| Recording does not play | recording_key, recording access token, storage settings, fleet recording backend |
| RAG answer is wrong | KB attachment, document status, Qdrant collection, trigger instructions |
Engineering Rules
- Keep live media logic out of VoxBridge. That belongs in VoxCore.
- Keep durable business state out of VoxCore. That belongs in VoxBridge and MongoDB.
- Do not expose raw recording URLs to CRMs when stable VoxBridge recording links are available.
- Do not hard-code client-specific behavior in shared API code; use bot config, system settings, brand config, or integration config.
- Protect production startup with real
JWT_SECRETandVOXCORE_SECRETvalues.
Related Docs
Architecture
How the four repos fit together.
Call lifecycle
How a call moves through VoxCore and VoxBridge.
Repos and boundaries
Ownership rules and key files for each repo.
CRM dialout API
How external systems trigger calls through VoxBridge.