🏗️ Sistem Mimarisi & Mühendislik Rasyoneli 🏗️ System Architecture & Engineering Rationale 🏗️ Systemarchitektur & Technische Rationale

AiPBX; kurumsal ağlardaki sıkı güvenlik duvarı engellerini, WebRTC medya aktarım zorluklarını, çoklu cihaz karmaşasını ve yüksek eşzamanlı anlık mesajlaşma ihtiyaçlarını çözmek için özel olarak mimarilendirilmiştir.

AiPBX is purposefully engineered to eliminate corporate firewall blockades, solve WebRTC NAT traversal challenges, streamline multi-device identity, and handle high-concurrency instant messaging.

AiPBX wurde zielgerichtet entwickelt, um restriktive Unternehmens-Firewalls zu überwinden, WebRTC-NAT-Herausforderungen zu lösen, Multi-Geräte-Identitäten zu vereinfachen und hochparalleles Instant Messaging zu bewältigen.

1. Bütünleşik Katmanlı Mimari (Layered Topology) 1. Unified Layered Architecture 1. Einheitliche Schichtenarchitektur

AiPBX, modüler ve gevşek bağlı (loosely coupled) çok katmanlı bir yapı üzerine inşa edilmiştir. İstemcilerden gelen tüm trafik tek bir noktada karşılanır ve protokol seviyesinde alt servislere yönlendirilir:

AiPBX is built on a modular, loosely coupled multi-tier architecture. All ingress traffic is multiplexed through a single entry point and routed cleanly at the protocol level:

AiPBX basiert auf einer modularen, lose gekoppelten Mehrschichtenarchitektur. Der gesamte eingehende Datenverkehr wird über einen einzigen Einstiegspunkt gebündelt und auf Protokollebene weitergeleitet:

ASCII Mimari Topolojisi ASCII Architectural Topology ASCII Architektur-Topologie

┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                      CLIENT LAYER                                       │
│   ┌───────────────────────────────┐               ┌─────────────────────────────────┐   │
│   │     Android Mobile App        │               │      Web Browser Client         │   │
│   │     (Kotlin + WebRTC/SIP)     │               │   (WebRTC Softphone + Portal)   │   │
│   └───────────────┬───────────────┘               └────────────────┬────────────────┘   │
└───────────────────┼────────────────────────────────────────────────┼────────────────────┘
                    │ HTTPS / WSS / TURNS (Single Port: 443)         │ HTTPS / WSS / TURNS
                    ▼                                                ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                   EDGE INGRESS: NGINX PORT 443 ALPN MULTIPLEXER (L4)                    │
│   Nginx TCP Stream module (ssl_preread on) — Transparent proxy evaluating ALPN bytes:   │
│                                                                                         │
│   ├── [ ALPN Present ] (http/1.1, h2: Web Browsers, Mobile REST API, Management)        │
│   │     └──► Streamed to Apache 2.4 TLS Termination (127.0.0.1:8443)                    │
│   │                                                                                     │
│   └── [ ALPN Empty / None ] (WebRTC TURNS media relay behind restrictive firewalls)     │
│         └──► Streamed to Coturn TURNS Service (127.0.0.1:5349)                          │
└───────────────────────────────────┬────────────────────────────────┬────────────────────┘
                                    │                                │
                     [ ALPN Present ]                                [ No ALPN ]
                                    ▼                                │
┌───────────────────────────────────────────────────────┐            │
│          APPLICATION & WEBSOCKET PROXY TIER           │            ▼
│  Apache 2.4 (127.0.0.1:8443 with TLS Termination)     │ ┌─────────────────────────────┐
│   ├── /                 ──► PHP 8 MVC Web Portal      │ │        COTURN RELAY         │
│   ├── /ws               ──► Asterisk WebRTC (8088/ws) │ │  TURNS Server (Port 5349)  │
│   └── /chat/ws          ──► Go Chat Engine (8086/ws)  │ │  Zero Media Loss for        │
│                                                       │ │  Symmetric NAT Traversal    │
│  Port 80: HTTP Redirect & Let's Encrypt ACME HTTP-01  │ └─────────────────────────────┘
└──────────┬────────────────────────┬───────────────────┘
           │                        │
           ▼                        ▼
┌─────────────────────┐  ┌─────────────────────┐
│      PHP 8 MVC      │  │     Asterisk 22     │
│     Web Portal      │  │     VoIP Engine     │
│  (Hardened Runtime) │  │    (PJSIP/WebRTC)   │
└──────────┬──────────┘  └──────────┬──────────┘
           │                        │
           │     AMI (Port 5038)    │
           ├────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│                                       DATA LAYER                                        │
│  MariaDB 11 (utf8mb4_unicode_ci) — Two-Tier Privilege Security Model:                   │
│   ├── aipbx_portal   (Runtime DML: SELECT, INSERT, UPDATE, DELETE only)                 │
│   └── aipbx_migrator (Schema DDL: Phinx Migrations only)                                │
└─────────────────────────────────────────────────────────────────────────────────────────┘

2. Neden Port 443 ALPN Stream Çoklama? 2. Why Port 443 ALPN Stream Multiplexing? 2. Warum Port 443 ALPN-Stream-Multiplexing?

Geleneksel VoIP santral kurulumlarında SIP sinyalleşmesi için UDP 5060, WebRTC WSS için 8089, STUN/TURN için 3478 veya 5349 gibi çok sayıda harici port açılması zorunludur. Ancak bankalar, hastaneler, üniversiteler ve kurumsal plaza ağları Port 80 ve 443 dışındaki tüm giden portları katı güvenlik duvarları (Firewall) ile bloke eder.

💡

AiPBX Çözümü: Nginx Layer 4 (L4) Stream modülü ve ssl_preread on direktifi sayesinde, TLS el sıkışmasındaki (ClientHello) Application-Layer Protocol Negotiation (ALPN) baytlarını inceler. SSL sertifikasını çözmeden şifreli trafiği alt servislere dağıtır.

Traditional PBX setups require opening numerous external ports: UDP 5060 for SIP, 8089 for WebRTC WSS, and 3478/5349 for STUN/TURN. However, modern corporate networks (banks, hospitals, universities, government offices) enforce strict firewalls that block all outbound traffic except ports 80 and 443.

💡

The AiPBX Solution: Nginx Layer 4 (L4) Stream module with ssl_preread on inspects the unencrypted Application-Layer Protocol Negotiation (ALPN) extension in the initial TLS ClientHello packet. It transparently multiplexes traffic without needing to decrypt the TLS session at the edge.

Klassische Telefonanlagen erfordern viele offene Ports: UDP 5060 für SIP, 8089 für WebRTC WSS und 3478/5349 für STUN/TURN. Moderne Unternehmensnetzwerke (Banken, Kliniken, Behörden) blockieren jedoch strikt alle ausgehenden Ports außer 80 und 443.

💡

Die AiPBX-Lösung: Das Nginx Layer-4 (L4) Stream-Modul mit ssl_preread on liest die Application-Layer Protocol Negotiation (ALPN) im TLS-ClientHello aus. Es leitet den Datenverkehr transparent weiter, ohne die SSL-Sitzung am Edge entschlüsseln zu müssen.

Nginx L4 Stream Yapılandırması: Nginx L4 Stream Configuration: Nginx L4 Stream-Konfiguration:

/etc/nginx/nginx.conf (Stream Multiplexer)

stream {
    map $ssl_preread_alpn_protocols $upstream_backend {
        # Standard web browsers and mobile REST API clients
        "~*http"        apache_https;
        "~*h2"          apache_https;
        
        # WebRTC TURNS media relay packets (send empty ALPN)
        default         coturn_turns;
    }

    upstream apache_https {
        server 127.0.0.1:8443;
    }

    upstream coturn_turns {
        server 127.0.0.1:5349;
    }

    server {
        listen 443;
        proxy_pass $upstream_backend;
        ssl_preread on;
        proxy_connect_timeout 5s;
        proxy_timeout 3600s;
    }
}

3. Dual-Endpoint PJSIP ve WebRTC Mimarisi 3. Dual-Endpoint PJSIP & WebRTC Architecture 3. Dual-Endpoint PJSIP & WebRTC Architektur

Piyasadaki birçok hazır PBX dağıtımı (FreePBX, Issabel vb.) tek bir dahili için aynı anda hem donanımsal masa telefonunu hem de WebRTC tarayıcıyı bağlamakta zorlanır. NAT arkasındaki masa telefonu ile WebRTC'nin şifreleme ve medya taşıma gereksinimleri taban tabana zıttır:

WebRTC (Tarayıcı & Mobil): WSS taşıyıcı, DTLS-SRTP şifreleme, ICE adayları, AVPF profil ve Opus ses kodeği gerektirir.
Masa Telefonu (IP Telefon / ATA): UDP veya TLS taşıyıcı, SDES-SRTP veya şifresiz RTP, SAVP/RTP profil ve G.711u/a kodeği kullanır.

Many legacy PBX solutions struggle to connect both a physical hardware phone and a WebRTC browser/mobile client to the same extension. Their transport and encryption profiles are mutually exclusive:

WebRTC (Browser & Mobile): Mandatory WSS transport, DTLS-SRTP encryption, ICE candidate negotiation, AVPF profile, and Opus audio codec.
Hardware Phone (Desktop IP Phone / ATA): Standard UDP/TLS transport, SDES-SRTP or plain RTP, SAVP profile, and G.711u/a or G.722 codecs.

Viele herkömmliche PBX-Distributionen scheitern daran, ein Tischtelefon und einen WebRTC-Browserclient gleichzeitig an einer einzigen Nebenstelle zu betreiben. Die Transport- und Verschlüsselungsprofile sind gegensätzlich:

WebRTC (Browser & Mobil): WSS-Transport, DTLS-SRTP-Verschlüsselung, ICE-Kandidaten, AVPF-Profil und Opus-Codec.
Tischtelefon (IP-Telefon / ATA): UDP/TLS-Transport, SDES-SRTP oder unverschlüsseltes RTP, SAVP-Profil und G.711/G.722-Codecs.

Endpoint ID	Kullanım Amacı Target Client Zielgerät	Taşıyıcı & Port Transport & Port Transport & Port	Şifreleme & Kodek Encryption & Codec Verschlüsselung & Codec
1000	Donanım IP Telefon / Masaüstü SIP Hardware IP Phone / Desktop SIP Hardware-IP-Telefon / Tischapparat	UDP / TLS (Port 5060/5061)	SDES-SRTP / G.711a, G.722, G.729
1000-webrtc	Web Tarayıcı & Native Mobil İstemci Web Browser & Native Mobile App Web-Browser & Native Mobil-App	WSS (Port 443 ALPN / 8089)	DTLS-SRTP + ICE / Opus (HD Audio)

📞

Çatal Zil (Forked Ringing): Dahili 1000 arandığında Asterisk dialplanı Dial(PJSIP/1000&PJSIP/1000-webrtc,30) komutuyla masadaki donanım telefonu ile cepteki mobil uygulamayı aynı anda çaldırır. İlk cevaplanan çağrıyı alır, diğeri sessizce kapanır.

Forked Ringing: When extension 1000 is dialed, Asterisk triggers Dial(PJSIP/1000&PJSIP/1000-webrtc,30), ringing both the desk phone and the mobile smartphone simultaneously. Whichever picks up first takes the call; the other cancels silently.

Parallelruf (Forked Ringing): Wird Nebenstelle 1000 angerufen, führt Asterisk Dial(PJSIP/1000&PJSIP/1000-webrtc,30) aus. Tischtelefon und Smartphone klingeln gleichzeitig. Das zuerst angenommene Gerät übernimmt das Gespräch.

4. Bağımsız Go Real-Time WebSocket Servisi 4. Standalone Go Real-Time WebSocket Service 4. Eigenständiger Go-Echtzeit-WebSocket-Dienst

PHP; kısa ömürlü HTTP istek-yanıt döngüleri için mükemmeldir, ancak binlerce açık WebSocket bağlantısını yönetmek için optimize edilmemiştir. AiPBX, santral içi anlık mesajlaşma ve çok katılımcılı grup sohbet motorunu saf Go (Golang) ile geliştirmiştir (/opt/aipbx/bin/aipbx-chat):

Mikro Bellek Tüketimi: 10.000 aktif eşzamanlı WebSocket bağlantısı yalnızca ~28 MB RAM tüketir.
Goroutine Kanalları: Her bağlantı için ağır sistem iş parçacığı yerine hafif Go kanalları kullanılır.
Sıfır Dış Bağımlılık: Tek bir statik ikili dosya olarak derlenir, ek kütüphane gerektirmez.
Varlık (Presence) & Yazıyor Bildirimi: Çevrimiçi/çevrimdışı durumu ve yazıyor bilgisi milisaniyeler içinde dağıtılır.

PHP is fantastic for short-lived HTTP request-response lifecycles, but inefficient for sustaining tens of thousands of idle WebSocket connections. AiPBX offloads instant messaging and group channels to a compiled Go service (/opt/aipbx/bin/aipbx-chat):

Micro Memory Footprint: 10,000 active concurrent WebSocket clients consume only ~28 MB of RAM.
Goroutine Concurrency: Channels handle message fanout asynchronously without OS thread overhead.
Zero External Dependencies: Single self-contained binary running as an isolated systemd daemon.
Presence & Typing Signals: Real-time typing indicators, read receipts, and online status distributed in milliseconds.

PHP eignet sich hervorragend für kurzlebige HTTP-Zyklen, ist jedoch ungeeignet für zehntausende dauerhafte WebSocket-Verbindungen. AiPBX nutzt für Instant Messaging und Gruppenkanäle einen kompakten Go-Dienst (/opt/aipbx/bin/aipbx-chat):

Minimaler RAM-Verbrauch: 10.000 aktive Verbindungen belegen lediglich ca. 28 MB Arbeitsspeicher.
Goroutine-Kanäle: Asynchrone Nachrichtenverteilung ohne Belastung durch Betriebssystem-Threads.
Keine externen Abhängigkeiten: Eine einzige statische Binärdatei, betrieben als systemd-Dienst.
Echtzeit-Präsenz & Tipp-Status: Tipp-Indikatoren, Lesebestätigungen und Online-Status in Millisekunden.

5. Asterisk Yapılandırma Senkronizasyon Döngüsü 5. Asterisk Configuration Sync Pipeline 5. Asterisk Konfigurations-Synchronisation

AiPBX'te Asterisk yapılandırma dosyaları asla elle düzenlenmez. Veritabanı (MariaDB), sistemin tek gerçeklik kaynağıdır (Single Source of Truth). Bir ayar değiştirildiğinde aşağıdaki atomik döngü işletilir:

Asterisk configuration files in AiPBX are never edited by hand. The MariaDB database is the single source of truth. Whenever changes occur, an atomic generation and rollback pipeline executes:

Asterisk-Konfigurationsdateien werden in AiPBX niemals manuell editiert. Die MariaDB-Datenbank ist die zentrale Informationsquelle. Bei Änderungen greift ein atomarer Generierungs- und Rollback-Zyklus:

Yapılandırma & Otomatik Geri Alma Akışı Config Generation & Automatic Rollback Flow Konfigurations- & Rollback-Ablauf

Web UI / REST API Request
        │
        ▼
Controller Validation & Auth Check
        │
        ▼
Service writes to MariaDB (DML)
        │
        ▼
Sync Generator (src/sync/*.php)
        ├── 1. Backs up existing file to .bak
        ├── 2. Queries DB and generates modular files under /etc/asterisk/pbx/*.conf
        └── 3. Issues Asterisk reload command (dialplan reload, queue reload...)
                │
                ├── [ SUCCESS ] ──► Updates audit log, removes .bak cleanly.
                └── [ FAILURE ] ──► AUTOMATIC ROLLBACK: Restores .bak immediately,
                                    prevents downtime, and logs error report.

6. İki Kademeli MariaDB Güvenlik Modeli 6. Two-Tier MariaDB Privilege Security Model 6. Zweistufiges MariaDB-Berechtigungsmodell

Kullanıcı Adı User Account Benutzerkonto	Kullanım Alanı Runtime Scope Einsatzbereich	SQL Yetkileri Granted SQL Privileges Erlaubte SQL-Rechte	Kısıtlanan Yetkiler Restricted Privileges Eingeschränkte Rechte
aipbx_portal	PHP Web Paneli & REST API PHP Web Portal & REST API PHP-Webportal & REST-API	SELECT, INSERT, UPDATE, DELETE	DROP, ALTER, CREATE, GRANT (Forbidden)
aipbx_migrator	Phinx Veritabanı Göçleri (CLI) Phinx Database Migrations (CLI) Phinx Datenbank-Migrationen (CLI)	CREATE, ALTER, INDEX, DROP	Local CLI only during schema migrations

← Önceki ← Previous ← Zurück Genel Bakış Overview Übersicht Sonraki → Next → Weiter → Çağrı Merkezi & Mola Call Center & Breaks Callcenter & Pausen