Repos and boundaries - Vox Systems

Ownership rules

The platform is five repos. Each has a clean primary job, so most bugs become easier once you place them in the right repo.

Problem	Start in
Call audio, STT/LLM/TTS, tool execution, transfer tool, voicemail, dead air, post-call packaging	`voxcore`
Bot config, API auth, calls table, campaigns API, CRM fetch/push, fleet selection, recordings, API keys	`voxbridge`
Form behavior, dashboard display, filters, campaign wizard, bot builder, agent console	`voxui`
Campaign pacing, SIP dial attempts, AMD screening, retry scheduling, attach-to-worker failures	`voxdialler`
Browser call widget, web token fetch, in-page call UI	`vohci-widget`

VoxCore

Primary files:

File	Why it matters
`src/voxcore/app.py`	FastAPI app, lifespan, call tracker, result outbox, Agent Desk outbox.
`src/voxcore/pipeline/factory.py`	Main Pipecat pipeline assembly. Start here for call behavior.
`src/voxcore/pipeline/live_prompt_cache.py`	Live prompt cache registry: Gemini `CachedContent` create/refresh, bounded LRU, version-based invalidation.
`src/voxcore/pipeline/tool_runtime.py`	Custom HTTP tool execution and telemetry.
`src/voxcore/routes/ws.py`	iCallMate WebSocket inbound.
`src/voxcore/routes/livekit.py`	LiveKit SIP inbound.
`src/voxcore/routes/dialout.py`	LiveKit SIP outbound.
`src/voxcore/routes/exotel.py`	Exotel Voicebot applet WebSocket inbound.
`src/voxcore/routes/_post_call.py`	Shared post-call finalization, auto dispositions, analysis, QC, webhook dispatch.
`src/voxcore/processors/post_call.py`	LLM post-call analysis and QC. Caches `genai.Client`; do not create one per call.
`src/voxcore/models/config.py`	Runtime config contract from VoxBridge to VoxCore.

VoxCore should not own durable customer/business state. It may write temporary outbox files and upload recordings, but VoxBridge remains the source of truth.

VoxBridge

Primary files:

File	Why it matters
`src/voxbridge/app.py`	FastAPI app, Mongo/Redis startup, indexes, routes, trunk health loop.
`src/voxbridge/routes/config.py`	Runtime config endpoint consumed by VoxCore.
`src/voxbridge/services/config_service.py`	Builds bot runtime config and call skeletons.
`src/voxbridge/routes/results.py`	Receives VoxCore call results.
`src/voxbridge/services/call_service.py`	Stores calls and pushes CRM post-call payloads.
`src/voxbridge/routes/sip.py`	CRM/admin dialout endpoint and VoxCore SIP lookup helpers.
`src/voxbridge/services/fleet_service.py`	Current outbound fleet selection.
`src/voxbridge/routes/campaigns.py`	Campaign CRUD, upload, lifecycle actions, attempt report.
`src/voxbridge/services/knowledge_*`	KB upload, chunking, embedding, Qdrant search.

VoxBridge should not run live media pipelines. It should issue config, store state, coordinate actions, and expose APIs.

VoxUI

Primary files:

File	Why it matters
`src/App.tsx`	Route map and role-based layouts.
`src/pages/BotCreate.tsx` / `src/pages/BotDetail.tsx`	Bot builder and edit workflow.
`src/hooks/useBotForm.ts`	Bot form state, defaults, serialization, validation.
`src/pages/CampaignCreate.tsx` / `src/pages/CampaignDetail.tsx`	Campaign setup and monitoring.
`src/pages/Settings.tsx`	System settings, API keys, fleet URLs, provider keys, MinIO, Agent Assist.
`src/components/bot/IntegrationTab.tsx`	Bot-specific CRM integration guide.
`src/pages/KnowledgeBases.tsx`	KB management.

VoxUI should not hard-code client-specific logic. Client/brand differences belong in brand config and build-time assets.

VoxDialler

Primary files:

File	Why it matters
`src/voxdialler/main.py`	Process entrypoint, health server, graceful shutdown.
`src/voxdialler/loop.py`	Campaign scheduling loop and state machine.
`src/voxdialler/fleet.py`	Polls VoxCore fleet capacity and reserves best worker.
`src/voxdialler/sip_dialler.py`	Creates LiveKit rooms and dials SIP participants.
`src/voxdialler/attacher.py`	Attaches answered LiveKit rooms to VoxCore workers.
`src/voxdialler/amd.py`	Answering machine detection screening.
`src/voxdialler/pacing.py`	Predictive pacing formula and abandon-rate brake.
`src/voxdialler/metrics.py`	Per-campaign rolling-window `answer_rate`, AHT, and `abandon_rate`.
`src/voxdialler/rate_limiter.py`	Per-carrier CPS token bucket (GCRA-style) keyed by carrier/trunk.
`src/voxdialler/trunks.py`	`OutboundTrunkResolver` + `TrunkResolution`; VoxBridge trunk lookup and per-carrier CPS/burst/channels.
`src/voxdialler/circuit_breaker.py`	Per-dependency async circuit breaker (closed/open/half-open) for fleet/SIP/Bridge calls.
`src/voxdialler/health.py`	Liveness (tick staleness → 503) and `/metrics` endpoints.

VoxDialler is intentionally separate from VoxBridge so campaign dispatch can evolve independently from the API server. The fifth repo is an embeddable browser call widget (React 19 + LiveKit client, built with Vite). It is mounted on a host page via window.Vohci.init({ botId, apiKey, label }), fetches a LiveKit access token, and opens a WebRTC call into a LiveKit room. VoxCore handles the room as a bot call through the /livekit/widget route and the same pipeline/post-call path as other transports. Primary files:

File	Why it matters
`src/index.tsx`	Global `Vohci.init` entry; mounts the widget on a host page.
`src/Widget.tsx`	Call state machine, LiveKit `Room` lifecycle, mic track, agent state.
`src/token.ts`	Fetches the LiveKit access token used to join the room.
`src/CallCard.tsx` / `src/Controls.tsx` / `src/AuraVisualizer.tsx`	Call UI, controls, and audio visualizer.

The widget owns no business state; it is a thin client that authenticates and joins a room. Bot config, auth, and results stay in VoxBridge/VoxCore.

​Ownership rules

​VoxCore

​VoxBridge

​VoxUI

​VoxDialler

​vohci-widget

Ownership rules

VoxCore

VoxBridge

VoxUI

VoxDialler

vohci-widget