Get started / ArchitectureAll pages
Get started

Architecture

What runs where, how a call travels through the system, and why it is split the way it is. Read this before you size servers or open firewall ports.

Runs on
One Ubuntu 24.04 server, or several
Call engines
1 to 4 Asterisk instances
Phones
Desk phones, browsers, carriers
Data
One MariaDB, on your server

The big picture

Every phone, browser and carrier talks to one front door, Kamailio. It protects the system, keeps track of where everyone is, and hands each call to one of the Asterisk instances, which run the actual phone system: extensions, IVR menus, queues, voicemail and the AI agent. rtpengine carries the audio and translates between browsers (WebRTC) and desk phones (plain SIP). The dashboard is where people work and where admins configure it all; it writes to the same database the call engines read from, so a change is live on the next call.

Your serverSIPWSSSIPNGdispatcherAudioSocketrealtimeSQLHTTPSDesk phonesSIP · UDP/TCP/TLSBrowser phoneWebRTC over WSSCarriersPhone numbersKamailioSIP edgertpengineAudio relayAsterisk ×1–4The phone systemAI voice agentSpeech ⇄ LLMDashboardNext.js · nginxMariaDBConfig · callsYour systemsWebhooks · API
One server can hold all of this; the Asterisk pool and the database can also move to their own servers.

Components

ComponentWhat it doesListens on
Kamailio 5.7Edge proxy: TLS and WebSocket termination, NAT handling, flood and brute-force ban, number normalisation, outbound fraud block list, carrier trunks, and the dispatcher that spreads calls over the Asterisk pool.5060 UDP/TCP, 5061 TLS, 4443 WSS
rtpengine 11All audio. Converts WebRTC (DTLS-SRTP, ICE, Opus) to plain RTP (G.711) and back, so any phone can call any other.30000–40000 UDP
Asterisk 20 ×1–4The PBX: extensions, IVR menus, queues, ring groups, voicemail, conference, music on hold, recording. Never exposed to the internet.127.0.0.1:5080 (+1 per instance)
AI voice agentPython service. Listens to the caller, asks the language model, speaks the answer, with barge-in.127.0.0.1:5001
MariaDBUsers, registrations, voicemail, IVR menus, queues, call records, dashboard data.local socket
DashboardThe web app (Next.js) plus its background worker: transcription, call analysis, webhook delivery.127.0.0.1:3000 behind nginx 443

How a phone signs in

Kamailio never checks passwords itself. It passes each REGISTER to Asterisk with a Path header, so Asterisk can find the phone again later through the same Kamailio. A user always lands on the same Asterisk instance, which keeps the sign-in challenge valid.

Phone or browserPhone or browserKamailioKamailioAsteriskAsteriskREGISTER 1001over UDP, TLS or WSS1REGISTER + Pathsame instance for the same user2401 challenge3401 challenge4REGISTER (with digest)5REGISTER + Path6Contact stored in the shared database: every instance can ring it200 OK8
Registration: the password check happens in Asterisk; Kamailio remembers the phone's real address.

How a call travels

Every call has two legs: caller → Asterisk and Asterisk → callee. Kamailio sits on both, and rtpengine converts the audio on both, so Asterisk only ever deals with plain G.711 audio. Here a customer calls the bank's number, goes through the IVR, and an agent answers in the browser.

CarrierCarrierKamailioKamailiortpenginertpengineAsteriskAsteriskAgent browserAgent browserINVITE +9221…source IP checked1offeropen media ports2INVITE (DID)dispatcher picks an instance3IVR menu runs: greeting, keys, checks with your API, queueINVITE 1001leg 2, via Path5INVITE over WSS6200 OK (Opus, DTLS)7answerWebRTC ⇄ RTP from now on8200 OK9
An inbound call from the phone network, answered by an agent on the browser phone.

Every direction works the same way

CallWhat happens to the audio
Desk phone → desk phonePlain RTP both ways; rtpengine relays it so phones behind NAT still hear each other.
Browser → browserEach browser leg is WebRTC (DTLS-SRTP, ICE, Opus); rtpengine turns both into plain RTP towards Asterisk.
Browser ⇄ desk phonertpengine converts only the browser leg; the desk phone leg stays plain RTP.
Anyone → phone networkKamailio normalises the number to +E.164, checks the block list and the per-user rate limit, then sends it out through the organization's carrier.
Phone network → numberThe carrier's address must be known; the number decides the destination: an IVR menu, a person, a queue, the AI agent or an app.

Numbering plan

Numbers inside an organization are short and predictable, so staff can dial anything from any phone.

DialReaches
100 – 799999A person's extension (3 to 6 digits, first digit 1–7). Rings every phone and browser signed in as that person; busy, no answer or offline goes to voicemail.
8000Echo test: hear yourself, to check audio.
8001The organization's default AI voice agent.
80xxA specific AI agent (each agent gets its own code).
81xxAn IVR menu.
82xxA call queue.
83xxA ring group.
8003 · 8004Music on hold · conference room.
*97Your voicemail.
0…, 00…, +…Outside numbers, through the organization's carrier.

Many organizations on one installation

Each organization (a bank, a hospital, a faculty) is fully separate: its own extensions, numbers, IVR menus, queues, recordings, users and history. Two organizations can both have an extension 1001; inside the system they are different accounts.

  • Phones sign in with the organization's SIP user name, <organization>-<extension>, shown on each person's Phone & devices page.
  • Every call carries its organization, so menus, queues, recording rules and call permissions are always the caller's own.
  • Admins only ever see their own organization. The platform operator manages the installation, not the organizations' calls.

Background services

Besides the call path, a few services keep everything in step. All of them are systemd units installed by install.sh.

UnitJob
dashboard.serviceThe web app and its worker. Every 5 seconds the worker runs queued jobs (transcription, analysis) and turns new calls, queue events and voicemail into webhook deliveries. Only one process (the leader) sends webhooks, so nothing goes out twice.
avr.serviceThe AI voice agent.
voip-sync.pathReloads carrier trunks into Kamailio when an admin changes them.
voip-trunk-status.timerShows each carrier's registration state in the dashboard.
voip-backup.timerNightly backup at 02:30 (see Install & operate).
Check that everything is runningShell
systemctl status kamailio rtpengine asterisk avr dashboard --no-pagersudo kamcmd dispatcher.list        # Asterisk instances and whether they answersudo asterisk -rx "pjsip show contacts"   # who is signed in

Next steps