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.
Components
| Component | What it does | Listens on |
|---|---|---|
| Kamailio 5.7 | Edge 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 11 | All 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–4 | The 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 agent | Python service. Listens to the caller, asks the language model, speaks the answer, with barge-in. | 127.0.0.1:5001 |
| MariaDB | Users, registrations, voicemail, IVR menus, queues, call records, dashboard data. | local socket |
| Dashboard | The 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.
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.
Every direction works the same way
| Call | What happens to the audio |
|---|---|
| Desk phone → desk phone | Plain RTP both ways; rtpengine relays it so phones behind NAT still hear each other. |
| Browser → browser | Each browser leg is WebRTC (DTLS-SRTP, ICE, Opus); rtpengine turns both into plain RTP towards Asterisk. |
| Browser ⇄ desk phone | rtpengine converts only the browser leg; the desk phone leg stays plain RTP. |
| Anyone → phone network | Kamailio 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 → number | The 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.
| Dial | Reaches |
|---|---|
100 – 799999 | A 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. |
8000 | Echo test: hear yourself, to check audio. |
8001 | The organization's default AI voice agent. |
80xx | A specific AI agent (each agent gets its own code). |
81xx | An IVR menu. |
82xx | A call queue. |
83xx | A ring group. |
8003 · 8004 | Music on hold · conference room. |
*97 | Your 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.
| Unit | Job |
|---|---|
dashboard.service | The 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.service | The AI voice agent. |
voip-sync.path | Reloads carrier trunks into Kamailio when an admin changes them. |
voip-trunk-status.timer | Shows each carrier's registration state in the dashboard. |
voip-backup.timer | Nightly backup at 02:30 (see Install & operate). |
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