callrouter is a TypeScript control plane plus Rust media/data plane for SIP routing, SIP device registration, SIP trunk calls, browser WebRTC softphones, a mediasoup SFU bootstrap for future browser meeting rooms, voicemail/fax storage, and a live operations dashboard. It is intentionally split so TypeScript owns configuration, REST/WebSocket APIs, and UI glue while Rust owns SIP, RTP, WebRTC media, codecs, mixing, jitter handling, fax transport, SFU worker/router state, and real-time call state.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Current Capabilities

SIP B2BUA behavior for SIP providers and LAN SIP devices, including dialog state, provider registration, digest auth retry, SDP negotiation, BYE/CANCEL handling, and routing decisions in Rust.
Browser WebRTC softphone signaling through the TypeScript dashboard, with WebRTC media sessions implemented in the Rust engine.
A call hub model: each call owns multiple legs and a 20 ms tick mix-minus mixer at a 48 kHz f32 internal bus.
Codec handling for Opus, G.722, PCMU, and PCMA through codec-lib, including per-leg transcoding, resampling, packet loss concealment, and jitter buffering.
Device registration push events from Rust into TypeScript, then into the dashboard status stream.
Route configuration for inbound and outbound calls with provider/device matching, number patterns, failover provider fields, browser notification flags, voicemail, fax, and IVR-related action fields.
Voicemail metadata through SmartData and WAV storage through SmartBucket, managed by VoiceboxManager.
Fax box and fax job metadata through SmartData and fax files through SmartBucket, backed by Rust fax handling that includes audio fax and T.38-related code paths.
Web dashboard and REST API on the configured webUiPort, served over HTTPS if .nogit/cert.pem and .nogit/key.pem exist, otherwise HTTP.
A mediasoup SFU bootstrap in a separate Rust sfu-engine process, with HTTP endpoints for SFU status and room/router creation.

Important Accuracy Notes

TypeScript does not handle raw SIP or RTP. It sends high-level commands to the Rust engine over @push.rocks/smartrust and receives high-level events back.
Browser WebRTC calls use a strict two-stage link flow. The browser first creates a standalone WebRTC session with webrtc-offer; only after webrtc-accept/linking can Rust attach that session to the call mixer.
Inbound route resolution and SIP-device multi-target forking are wired in Rust. Registered SIP targets on an inbound route are rung in parallel; the first SIP device 2xx wins and loser branches are cancelled/absorbed.
ringBrowsers currently controls browser notifications. Browser WebRTC clients do not yet race SIP devices in the first-answer-wins model.
Direct voicemailBox, faxBox, and ivrMenuId inbound routes are handled in Rust. noAnswerTimeout currently falls back to voicemail for unanswered SIP-device branches; IVR/fax no-answer fallback is still not implemented.
IVR prompt playback and DTMF collection are wired, but executing configured IVR actions is still incomplete.
The /api/transfer HTTP endpoint currently returns 501 not yet implemented.
The mediasoup SFU currently bootstraps workers and per-room routers only. Browser producer/consumer signaling and the SIP/audio bridge into rooms are still future work.
sfu-engine is a separate Rust process because mediasoup and the SIP proxy's ONNX/TTS stack both include native C++ FlatBuffers symbols that cannot be linked into the same executable safely.

Architecture

Browser dashboard and softphone
        |
        | HTTP + WebSocket signaling
        v
TypeScript control plane
  ts/sipproxy.ts
  ts/frontend.ts
  ts/webrtcbridge.ts
  ts/config.ts
  ts/proxybridge.ts
        |
        | JSON-over-stdio via @push.rocks/smartrust
        v
Rust proxy-engine
  SIP transport and dialog state
  Call manager and call hub
  RTP port pool and RTP I/O
  48 kHz f32 mix-minus mixer
  WebRTC sessions
  Fax, voicemail, TTS, recorder, tool legs
         |
         | SIP/RTP/UDPTL/WebRTC media
         v
SIP providers, SIP devices, and browser clients

TypeScript SFU API
  ts/sfubridge.ts
        |
        | JSON-over-stdio via @push.rocks/smartrust
        v
Rust sfu-engine
  mediasoup worker and room routers

Key Files

Path	Role
`ts/sipproxy.ts`	Process entry point. Loads config, starts web UI, starts Rust, wires event handlers, and handles shutdown.
`ts/config.ts`	`.nogit/config.json` schema, defaults, and validation.
`ts/proxybridge.ts`	Typed command bridge to the Rust `proxy-engine` binary.
`ts/sfubridge.ts`	Typed command bridge to the Rust `sfu-engine` binary.
`ts/frontend.ts`	HTTP API, static dashboard serving, status WebSocket, and WebRTC message routing.
`ts/webrtcbridge.ts`	Browser device registration and WebSocket-to-device mapping.
`ts/voicebox.ts`	Voicemail box config, WAV metadata, unheard counts, and message CRUD.
`ts/faxbox.ts`	Fax inbox metadata and TIFF file tracking.
`ts/faxjobs.ts`	Outbound/inbound fax job state persistence.
`rust/crates/proxy-engine/src/call_manager.rs`	Central call registry, SIP routing, B2BUA state, route resolution, fax metadata, and call orchestration.
`rust/crates/proxy-engine/src/mixer.rs`	20 ms mix-minus engine with 48 kHz f32 processing, codec boundaries, jitter, PLC, DTMF, and tool-leg audio.
`rust/crates/proxy-engine/src/webrtc_engine.rs`	Browser WebRTC sessions.
`rust/crates/proxy-engine/src/fax_engine.rs`	Fax transfer engine using `spandsp` and `udptl`.
`rust/crates/sfu-engine/src/sfu_manager.rs`	mediasoup worker and per-room router manager.
`rust/crates/sip-proto/`	Zero-dependency SIP data library for parsing, serializing, dialogs, SDP helpers, digest auth, and URI rewriting.
`ts_web/`	Lit/dees-element dashboard views and WebRTC browser client state.

Storage and Environment

callrouter persists runtime configuration and message metadata through SmartData and stores media/files through SmartBucket. Set these storage variables before first start:

Variable	Purpose
`CALLROUTER_MONGODB_URL`	MongoDB connection URL for SmartData.
`CALLROUTER_S3_ENDPOINT`	S3-compatible SmartBucket endpoint.
`CALLROUTER_S3_BUCKET`	Bucket for voicemail, fax, and cached media objects.
`CALLROUTER_S3_ACCESS_KEY`	S3 access key.
`CALLROUTER_S3_SECRET_KEY`	S3 secret key.

Optional storage variables include CALLROUTER_MONGODB_NAME, CALLROUTER_MONGODB_USER, CALLROUTER_MONGODB_PASS, CALLROUTER_S3_PORT, CALLROUTER_S3_USESSL, and CALLROUTER_S3_REGION. Legacy SIPROUTER_* names and common MONGODB_* / S3_* aliases are still accepted for existing deployments.

If no config exists in SmartData yet, callrouter imports a legacy .nogit/config.json when present. Otherwise it creates the initial config from environment variables. Required initial config variables are CALLROUTER_LAN_IP and CALLROUTER_INITIAL_DEVICE_ADDRESS; optional variables include CALLROUTER_LAN_PORT, CALLROUTER_PUBLIC_IP, CALLROUTER_RTP_PORT_MIN, CALLROUTER_RTP_PORT_MAX, CALLROUTER_WEB_UI_PORT, CALLROUTER_INITIAL_DEVICE_ID, CALLROUTER_INITIAL_DEVICE_DISPLAY_NAME, and CALLROUTER_INITIAL_DEVICE_EXTENSION.

Configuration

The configuration shape stored in SmartData, or imported once from legacy .nogit/config.json, looks like this:

{
  "proxy": {
    "lanIp": "192.168.1.100",
    "lanPort": 5070,
    "publicIpSeed": null,
    "rtpPortRange": { "min": 20000, "max": 20200 },
    "webUiPort": 3060
  },
  "providers": [
    {
      "id": "main-trunk",
      "displayName": "Main SIP trunk",
      "domain": "sip.example.net",
      "outboundProxy": { "address": "sip.example.net", "port": 5060 },
      "username": "trunk-user",
      "password": "trunk-password",
      "registerIntervalSec": 300,
      "codecs": [9, 0, 8, 101],
      "quirks": { "earlyMediaSilence": false }
    }
  ],
  "devices": [
    {
      "id": "desk-phone",
      "displayName": "Desk Phone",
      "expectedAddress": "192.168.1.50",
      "extension": "100"
    }
  ],
  "routing": {
    "routes": [
      {
        "id": "outbound-default",
        "name": "Outbound via main trunk",
        "priority": 100,
        "enabled": true,
        "match": { "direction": "outbound" },
        "action": { "provider": "main-trunk" }
      },
      {
        "id": "inbound-main",
        "name": "Inbound main number",
        "priority": 200,
        "enabled": true,
        "match": {
          "direction": "inbound",
          "sourceProvider": "main-trunk",
          "numberPattern": "+49421219694"
        },
        "action": {
          "targets": ["desk-phone"],
          "ringBrowsers": true,
          "voicemailBox": "main"
        }
      }
    ]
  },
  "contacts": [],
  "voiceboxes": [
    {
      "id": "main",
      "enabled": true,
      "greetingText": "Please leave a message after the tone.",
      "greetingVoice": "af_bella",
      "noAnswerTimeoutSec": 25,
      "maxRecordingSec": 120,
      "maxMessages": 50
    }
  ],
  "faxboxes": [],
  "ivr": {
    "enabled": false,
    "entryMenuId": "main-menu",
    "menus": []
  }
}

For inbound SIP-device routes, action.targets can list multiple registered device IDs. callrouter forks the inbound INVITE to each registered target, forwards the first SIP device answer to the provider, and sends CANCEL to the remaining SIP device branches. If every device rejects, the final rejection is forwarded upstream.

For inbound SIP-device routes, action.noAnswerTimeout sends an unanswered call to the configured voicemailBox or the default voicemail box. If noAnswerTimeout is omitted but voicemailBox is set, the voicebox noAnswerTimeoutSec value is used, falling back to 25 seconds.

Persistent Files

Path	Purpose
SmartData	Main app config, fax job state, fax metadata, and voicemail metadata.
SmartBucket	Voicemail, fax, and cached media objects.
`.nogit/config.json`	Legacy config import source when SmartData has no stored app config yet.
`.nogit/cert.pem` and `.nogit/key.pem`	Optional HTTPS certificate for the dashboard.
`.nogit/cache/`	Local cache for fetched SmartBucket objects.
`.nogit/voicemail/{boxId}/`	Legacy voicemail files used by older local deployments.
`.nogit/fax/inboxes/{boxId}/`	Legacy fax inbox files used by older local deployments.
`.nogit/fax/jobs.json`	Legacy fax job state used by older local deployments.
`.nogit/prompts/`	Cached prompt/TTS assets used by call flows.
`sip_trace.log`	Runtime log written by `ts/sipproxy.ts`.

HTTP and WebSocket API

Endpoint	Purpose
`GET /api/status`	Full status snapshot for providers, devices, calls, and dashboard state.
`GET /api/sfu/status`	Return SFU worker/room status without starting the SFU process.
`POST /api/sfu/rooms`	Create or return a mediasoup room/router for `{ "roomId": "..." }`.
`DELETE /api/sfu/rooms/:roomId`	Delete a mediasoup room/router, dropping the router resource.
`POST /api/call`	Originate an outbound call.
`POST /api/hangup`	Hang up a call.
`POST /api/fax`	Start an outbound fax.
`GET /api/fax/jobs`	List fax jobs.
`GET /api/fax/inboxes/:boxId`	List fax inbox messages.
`GET /api/fax/inboxes/:boxId/:messageId/file`	Stream a fax TIFF.
`DELETE /api/fax/inboxes/:boxId/:messageId`	Delete a fax message.
`POST /api/call/:id/addleg`	Add a registered SIP device leg to an active call.
`POST /api/call/:id/addexternal`	Add an external dial-out leg to an active call.
`POST /api/call/:id/removeleg`	Remove a leg from a call.
`POST /api/transfer`	Present but returns `501 not yet implemented`.
`GET /api/config`	Read sanitized config.
`POST /api/config`	Update config and trigger runtime reload where possible.
`GET /api/voicemail/:boxId`	List voicemail messages.
`GET /api/voicemail/:boxId/unheard`	Get unheard voicemail count.
`GET /api/voicemail/:boxId/:messageId/audio`	Stream voicemail WAV audio.
`POST /api/voicemail/:boxId/:messageId/heard`	Mark voicemail as heard.
`DELETE /api/voicemail/:boxId/:messageId`	Delete voicemail metadata and WAV file.
`WS /ws`	Status updates, logs, WebRTC signaling, and browser phone events.

Build and Run

pnpm install
pnpm run buildRust
pnpm run bundle
pnpm start

Full build:

pnpm build

Docker build scripts are also present:

pnpm run build:docker
pnpm run release:docker

pnpm run buildRust uses tsrust. Per the project notes, do not replace that with a direct cargo build when validating the packaged Rust output. The configured build path cross-compiles the Rust proxy-engine and sfu-engine binaries for Linux amd64 and arm64 targets. Cross-building mediasoup-sys for arm64 also requires qemu-aarch64-static so Meson can run target-built helper tools while compiling the worker library.

Project Map

callrouter/
├── ts/                      # TypeScript control plane
├── ts_web/                  # Browser dashboard
├── rust/
│   └── crates/
│       ├── codec-lib/       # Codec and transcoding helpers
│       ├── proxy-engine/    # Rust SIP/RTP/WebRTC/fax engine
│       ├── sfu-engine/      # Rust mediasoup SFU worker/router engine
│       └── sip-proto/       # SIP message/dialog/SDP library
├── html/                    # Dashboard HTML shell
├── dist_rust/               # Built Rust binaries
├── dist_ts_web/             # Bundled web UI
└── .nogit/                  # Local legacy config, object cache, secrets, and prompt cache

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

callrouter