# jambonz/jambonz-feature-server architecture

> Architecture diagram of the GitHub repository jambonz/jambonz-feature-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jambonz/jambonz-feature-server
- Repository: https://github.com/jambonz/jambonz-feature-server

## Overview

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: [`lib/session/call-session.js`](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/call-session.js) (Sessions), [`app.js`](https://github.com/jambonz/jambonz-feature-server/blob/main/app.js) (App entry), [`lib/tasks/make_task.js`](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/make_task.js) (Task engine), [`lib/http-routes/index.js`](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/index.js) (HTTP routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_northbound["Northbound API"]
  node_node_http_routes["HTTP routes<br/>northbound surface<br/>[index.js]"]
  node_node_api_calls["Call API<br/>api handlers<br/>[create-call.js]"]
  node_node_api_conversation["Queue & conf<br/>api handlers<br/>[enqueue.js]"]
  node_node_api_validation["Schemas<br/>validation<br/>[create-call.js]"]
end

subgraph group_group_core["Core Engine"]
  node_node_sessions["Sessions<br/>session layer<br/>[call-session.js]"]
  node_node_inbound["Inbound call<br/>session type"]
  node_node_rest["REST call<br/>session type"]
  node_node_sms_siprec["SMS/SIPREC<br/>session types"]
  node_node_tasks["Task engine<br/>call control<br/>[make_task.js]"]
  node_node_task_core["Call tasks<br/>[dial.js]"]
  node_node_task_ai["AI tasks<br/>speech/agent tasks<br/>[index.js]"]
end

subgraph group_group_southbound["Southbound Integrations"]
  node_node_utils_sip["SIP helpers<br/>telephony utils<br/>[sdp-utils.js]"]
  node_node_utils_runtime["Runtime utils<br/>ops utils"]
  node_node_state[("State stores<br/>external state<br/>[db-utils.js]")]
  node_node_speech(("Speech vendors<br/>external integrations"))
  node_node_telephony{{"Telephony plane<br/>external systems"}}
  node_node_cloud{{"Cloud services<br/>external systems"}}
end

subgraph group_group_support["Support & Runtime"]
  node_node_app["App entry<br/>startup<br/>[app.js]"]
  node_node_bin["Pre-stop hook<br/>lifecycle hook"]
  node_node_config["Config<br/>[config.js]"]
  node_node_dyn_apps["Dynamic apps<br/>data-driven apps<br/>[dynamic-apps.js]"]
end

node_node_app -->|"loads"| node_node_config
node_node_app -->|"starts"| node_node_http_routes
node_node_app -->|"creates"| node_node_sessions
node_node_http_routes -->|"dispatches"| node_node_api_calls
node_node_http_routes -->|"dispatches"| node_node_api_conversation
node_node_api_calls -->|"validates"| node_node_api_validation
node_node_api_calls -->|"spawns"| node_node_sessions
node_node_api_conversation -->|"drives"| node_node_sessions
node_node_sessions -->|"specializes"| node_node_inbound
node_node_sessions -->|"specializes"| node_node_rest
node_node_sessions -->|"specializes"| node_node_sms_siprec
node_node_sessions -->|"executes"| node_node_tasks
node_node_tasks -->|"runs"| node_node_task_core
node_node_tasks -->|"routes to"| node_node_task_ai
node_node_task_core -->|"uses"| node_node_utils_sip
node_node_task_core -->|"reads/writes"| node_node_state
node_node_task_ai -->|"integrates"| node_node_speech
node_node_utils_sip -->|"controls"| node_node_telephony
node_node_utils_runtime -->|"coordinates"| node_node_state
node_node_utils_runtime -->|"calls"| node_node_cloud
node_node_dyn_apps -->|"feeds"| node_node_tasks
node_node_bin -->|"hooks"| node_node_app
node_node_app -->|"connects"| node_node_telephony

click node_node_app "https://github.com/jambonz/jambonz-feature-server/blob/main/app.js"
click node_node_bin "https://github.com/jambonz/jambonz-feature-server/blob/main/bin/k8s-pre-stop-hook.js"
click node_node_config "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/config.js"
click node_node_http_routes "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/index.js"
click node_node_api_calls "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/api/create-call.js"
click node_node_api_conversation "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/api/enqueue.js"
click node_node_api_validation "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/schemas/create-call.js"
click node_node_sessions "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/call-session.js"
click node_node_inbound "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/inbound-call-session.js"
click node_node_rest "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/rest-call-session.js"
click node_node_sms_siprec "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/sms-call-session.js"
click node_node_tasks "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/make_task.js"
click node_node_task_core "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/dial.js"
click node_node_task_ai "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/llm/index.js"
click node_node_utils_sip "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/sdp-utils.js"
click node_node_utils_runtime "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/background-task-manager.js"
click node_node_dyn_apps "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/dynamic-apps.js"
click node_node_state "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/db-utils.js"
click node_node_speech "https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/tts-streaming-buffer.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_http_routes,node_node_api_calls,node_node_api_conversation,node_node_api_validation toneBlue
class node_node_sessions,node_node_inbound,node_node_rest,node_node_sms_siprec,node_node_tasks,node_node_task_core,node_node_task_ai toneAmber
class node_node_utils_sip,node_node_utils_runtime,node_node_state,node_node_speech,node_node_telephony,node_node_cloud toneMint
class node_node_app,node_node_bin,node_node_config,node_node_dyn_apps toneRose
```

## Components

### Northbound API

HTTP surfaces that receive call instructions from jambonz control services.

- [HTTP routes](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/index.js): northbound surface · Top-level HTTP routing for the API surface. · `lib/http-routes/index.js`
- [Call API](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/api/create-call.js): api handlers · Create and update call operations plus related call control. · `lib/http-routes/api/create-call.js`
- [Queue & conf](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/api/enqueue.js): api handlers · Enqueue, dequeue, conferencing, and message-related call actions. · `lib/http-routes/api/enqueue.js`
- [Schemas](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/http-routes/schemas/create-call.js): validation · 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](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/call-session.js): session layer · Per-call session objects that coordinate state and task execution. · `lib/session/call-session.js`
- [Inbound call](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/inbound-call-session.js): session type · Session variant for inbound telephony calls. · `lib/session/inbound-call-session.js`
- [REST call](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/rest-call-session.js): session type · Session variant for API-originated outbound or bridged calls. · `lib/session/rest-call-session.js`
- [SMS/SIPREC](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/session/sms-call-session.js): session types · Session variants for messaging and SIPREC recording flows. · `lib/session/sms-call-session.js`
- [Task engine](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/make_task.js): call control · Main application logic boundary that executes jambonz tasks. · `lib/tasks/make_task.js`
- [Call tasks](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/dial.js): tasks · Core call actions such as say, dial, gather, listen, play, hangup, enqueue, dequeue, and conference. · `lib/tasks/dial.js`
- [AI tasks](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/tasks/llm/index.js): speech/agent 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](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/sdp-utils.js): telephony utils · SIP, SDP, and media endpoint utilities for signaling and media control. · `lib/utils/sdp-utils.js`
- [Runtime utils](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/background-task-manager.js): ops utils · Tracing, request helpers, background jobs, SBC health, DTMF, transcription, and process monitoring. · `lib/utils/background-task-manager.js`
- [State stores](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/db-utils.js): external state · Redis/MySQL-backed coordination and lookup state used by the server. · `lib/utils/db-utils.js`
- [Speech vendors](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/utils/tts-streaming-buffer.js): external integrations · Speech and AI vendor integrations reached during active calls. · `lib/utils/tts-streaming-buffer.js`
- **Telephony plane**: external systems · Drachtio, FreeSWITCH, SBCs, and related SIP/media infrastructure.
- **Cloud services**: external systems · 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](https://github.com/jambonz/jambonz-feature-server/blob/main/app.js): startup · Process entry point that boots the feature server. · `app.js`
- [Pre-stop hook](https://github.com/jambonz/jambonz-feature-server/blob/main/bin/k8s-pre-stop-hook.js): lifecycle hook · Kubernetes/cluster shutdown hook for graceful stopping. · `bin/k8s-pre-stop-hook.js`
- [Config](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/config.js): env config · Environment-driven server configuration and runtime setup. · `lib/config.js`
- [Dynamic apps](https://github.com/jambonz/jambonz-feature-server/blob/main/lib/dynamic-apps.js): data-driven apps · Loads or synthesizes app behavior from JSON and external configuration. · `lib/dynamic-apps.js`

## Connections

- 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.