How jambonz/jambonz-feature-server works
1. This repository is the Node.js “feature server” for the jambonz platform. It sits between the API layer and live telephony infrastructure, translating high-level call applications into SIP/media actions.
2. The entry point is app.js, with startup/runtime helpers under bin/ and lib/utils/. The server is configured entirely through environment variables and is designed to run under pm2 or in Docker/Kubernetes.
3. There are two major external control planes:
- an HTTP API surface for jambonz-api-server under lib/http-routes/
- a SIP/media control plane for telephony infrastructure, primarily Drachtio and FreeSWITCH, plus SBCs and Redis/MySQL-backed state
4. The HTTP API layer is where app-level instructions are received. Routes in lib/http-routes/api/ cover call creation, update, dequeue/enqueue, conferencing, and messaging. Request validation is schema-driven (lib/http-routes/schemas/) and errors are normalized through shared helpers.
5. The core execution model is session-based. lib/session/ contains distinct session types for inbound calls, REST-originated calls, SMS, SIPREC, confirm/record-style flows, and tracking. These session objects encapsulate per-call state and coordinate task execution over the life of a call.
6. Call behavior is driven by a task engine under lib/tasks/. Each task represents one action in a jambonz application, such as say, dial, gather, listen, play, hangup, enqueue, dequeue, conference, transcribe, and various SIP-specific actions. The task layer is the main business-logic boundary of the repo.
7. The service supports multiple speech/AI integrations through specialized task submodules:
- Dialogflow under lib/tasks/dialogflow/
- LLM/voice-agent streaming integrations under lib/tasks/llm/
- Lex, Rasa, and STT/TTS-specific helpers
This means call media can be routed into external ASR/TTS/agent systems during an active session.
8. Media and signaling utilities in lib/utils/ are a significant architectural layer. They handle SIP/SDP manipulation, call tracing, media endpoint selection, DTMF collection, transcription timing, websocket and HTTP request helpers, SBC health/pinging, and background job coordination.
9. Persistent and shared state is externalized:
- MySQL is used for configuration/accounting/data lookups
- Redis is used for ephemeral coordination and runtime state
- AWS services are used for TTS/STT-related support and SNS lifecycle notifications
- Google credentials are required for some speech integrations
This keeps the server largely stateless aside from in-memory per-session objects.
10. The repository also includes lifecycle and cluster-management concerns, such as pre-stop hooks, AWS SNS lifecycle handling, cron jobs, and process monitoring. These indicate the server participates in a horizontally scaled telephony cluster and needs graceful shutdown behavior.
11. lib/dynamic-apps.js and data/example-voicemail-greetings.json show that some call behavior is data-driven rather than hardcoded. The server can load or synthesize application behavior from JSON payloads and external configuration.
12. Testing is broad and integration-heavy. The test/ tree includes unit tests plus SIP scenario files, DB setup scripts, websocket mocks, Docker-based testbeds, and sample app payloads. That reflects the repository’s architecture: a call-control engine whose correctness depends on SIP signaling, media behavior, and external service interactions.
13. For an architecture diagram, the key boundaries are:
- northbound: HTTP API requests from jambonz control services
- core: session + task engine
- southbound: Drachtio/SIP, FreeSWITCH/media, SBCs, Redis, MySQL, and speech/AI vendors
The server’s central role is to convert API-driven call instructions into live telephony and media workflows.
Main entry points: call-session.js Sessions · app.js App entry · make_task.js Task engine · index.js HTTP routes
Components 21
Northbound API
HTTP surfaces that receive call instructions from jambonz control services.
- HTTP routes · Top-level HTTP routing for the API surface.
lib/http-routes/index.js - Call API · Create and update call operations plus related call control.
lib/http-routes/api/create-call.js - Queue & conf · Enqueue, dequeue, conferencing, and message-related call actions.
lib/http-routes/api/enqueue.js - Schemas · Request schemas and normalized API error handling.
lib/http-routes/schemas/create-call.js
Core Engine
Session lifecycle and task execution that drive live call behavior.
- Sessions · Per-call session objects that coordinate state and task execution.
lib/session/call-session.js - Inbound call · Session variant for inbound telephony calls.
lib/session/inbound-call-session.js - REST call · Session variant for API-originated outbound or bridged calls.
lib/session/rest-call-session.js - SMS/SIPREC · Session variants for messaging and SIPREC recording flows.
lib/session/sms-call-session.js - Task engine · Main application logic boundary that executes jambonz tasks.
lib/tasks/make_task.js - Call tasks · Core call actions such as say, dial, gather, listen, play, hangup, enqueue, dequeue, and conference.
lib/tasks/dial.js - AI tasks · Speech and agent integrations for Dialogflow, LLM voice agents, Lex, and Rasa.
lib/tasks/llm/index.js
Southbound Integrations
Telephony, media, state, and vendor integrations used during active sessions.
- SIP helpers · SIP, SDP, and media endpoint utilities for signaling and media control.
lib/utils/sdp-utils.js - Runtime utils · Tracing, request helpers, background jobs, SBC health, DTMF, transcription, and process monitoring.
lib/utils/background-task-manager.js - State stores · Redis/MySQL-backed coordination and lookup state used by the server.
lib/utils/db-utils.js - Speech vendors · Speech and AI vendor integrations reached during active calls.
lib/utils/tts-streaming-buffer.js - Telephony plane · Drachtio, FreeSWITCH, SBCs, and related SIP/media infrastructure.
- Cloud services · AWS and Google services used for lifecycle, STT/TTS support, and credentials.
Support & Runtime
Startup, configuration, and operational helpers used across the service.
- App entry · Process entry point that boots the feature server.
app.js - Pre-stop hook · Kubernetes/cluster shutdown hook for graceful stopping.
bin/k8s-pre-stop-hook.js - Config · Environment-driven server configuration and runtime setup.
lib/config.js - Dynamic apps · Loads or synthesizes app behavior from JSON and external configuration.
lib/dynamic-apps.js
Connections 23
- App entry → Config: loads · Bootstraps runtime from environment-based configuration.
- App entry → HTTP routes: starts · Exposes the northbound HTTP API surface.
- App entry → Sessions: creates · Initializes per-call session management.
- HTTP routes → Call API: dispatches · Routes call-creation and call-update requests.
- HTTP routes → Queue & conf: dispatches · Routes messaging, enqueue/dequeue, and conference actions.
- Call API → Schemas: validates · Applies schema checks and normalized error handling.
- Call API → Sessions: spawns · Creates or updates sessions in response to API instructions.
- Queue & conf → Sessions: drives · Maps queueing, conference, and messaging operations onto active sessions.
- Sessions → Inbound call: specializes · Inbound call handling.
- Sessions → REST call: specializes · API-originated call handling.
- Sessions → SMS/SIPREC: specializes · Messaging and recording-oriented session flows.
- Sessions → Task engine: executes · Delegates call behavior to the task engine.
- Task engine → Call tasks: runs · Executes the main call-control actions.
- Task engine → AI tasks: routes to · Hands media to speech, LLM, and agent integrations when needed.
- Call tasks → SIP helpers: uses · Depends on signaling and media utilities for call actions.
- Call tasks → State stores: reads/writes · Uses shared runtime state and persistence-backed lookups.
- AI tasks → Speech vendors: integrates · Connects call media to external speech and AI providers.
- SIP helpers → Telephony plane: controls · Interacts with SIP/media infrastructure and SBCs.
- Runtime utils → State stores: coordinates · Uses Redis/MySQL-backed coordination and background jobs.
- Runtime utils → Cloud services: calls · Uses cloud services for lifecycle and speech-related support.
- Dynamic apps → Task engine: feeds · Provides data-driven application behavior to the task engine.
- Pre-stop hook → App entry: hooks · Supports graceful shutdown around the main process.
- App entry → Telephony plane: connects · Anchors the server to live telephony infrastructure.