Telecom Engines & Infrastructure Nodes Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Distributed Node Synchronization
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The Telecom Engines & Infrastructure Nodes module (public.telecom_nodes and telecomNodeService.ts) is the central orchestration bridge connecting Ring2All Billing to remote telephony switches. It manages the lifecycle, API authentication, health monitoring, and automated provisioning across both Ring2All PBX (Class 5 Core) and Ring2All SBC (Class 4 Core) instances.

Supported Engine Architectures

• Ring2All PBX (ring2all_pbx): Class 5 enterprise voice engine based on Telephony Server. BSS pushes tenant creation, domain assignment, extension quotas, and inbound DID routing rules.
• Ring2All SBC (kalixor_sbc): Class 4 carrier session border controller based on Kamailio and RTPEngine. BSS pushes SIP trunk authentication credentials, dispatcher set load balancing, LCR prefix tables, and anti-fraud lockouts.

 ┌────────────────────────────────────────────────────────────────────────┐
 │                   Ring2All Billing Admin Orchestrator                  │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
           ┌─────────────────────────┴─────────────────────────┐
           │ Secure REST API (X-API-Key)                       │ Secure REST API (X-API-Key)
           ▼                                                   ▼
 ┌───────────────────────────────────┐               ┌───────────────────────────────────┐
 │   Node: Ring2All PBX (Class 5)    │               │   Node: Ring2All SBC (Class 4)    │
 │   URL: https://192.168.10.31      │               │   URL: https://192.168.10.32      │
 │   • Auto-creates Tenants & Domains│               │   • Auto-creates SIP Trunks       │
 │   • Provisions Mini-PBX Extensions│               │   • Ingests Perimeter CDRs        │
 │   • Binds Inbound DID Routing     │               │   • Enforces Dialing Whitelists   │
 │   • Enforces Audio Storage Quotas │               │   • Executes Real-time Call Drops │
 └───────────────────────────────────┘               └───────────────────────────────────┘

---

2. Module Overview (Commercial & Business Value)

• Zero-Touch Automated Provisioning: Eliminates manual voice switch configuration. When a customer subscribes to a plan in the billing portal, Ring2All Billing immediately provisions the PBX tenant and SBC trunk via REST APIs.
• Geographic & Multi-Data Center Scalability: Enables horizontal expansion across multiple regional PBX and SBC clusters (e.g. US-East, Europe, Latin America) while maintaining unified billing and invoicing.
• Proactive Failover & High Availability: Continuously monitors node response latency and health. If a primary voice core becomes unreachable, the BSS alerts the NOC and reroutes new customer provisioning to secondary backup engines.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Infrastructure Control	Registers new telephony nodes, rotates API authentication keys, defines default cluster nodes, and oversees multi-datacenter topology.
NOC Engineer	Read & Connectivity Health	Monitors real-time ping latencies, investigates node disconnection alerts, and executes diagnostic interconnect tests.
Telecom Systems Architect	Configuration & Routing Policy	Configures API endpoints, assigns default SBC trunks for carrier termination, and verifies Kamailio/FreeSWITCH socket synchronization.
Billing Analyst	Read & Tenant Association	Verifies that customer subscriptions are linked to operational voice engine nodes.

---

4. Visual Interface & Form Structure

4.1 Telecom Engines (List View)

The Telecom Engines & Infrastructure Nodes list displays all registered voice cores with real-time connectivity status, round-trip latency in milliseconds, environment badges, and instant diagnostic ping buttons.

4.2 Telecom Engine Configuration Form (Form View)

The Telecom Engine Configuration form manages API endpoint URLs, mutual TLS certificates, API secret keys, and default engine assignments.

4.3 Form Parameter Reference

Parameter Name	Data Type	Required	Default Value	Description & Business Rules
Node / Engine Name	String	Yes	—	Clear identifier for the voice core (e.g. Ring2All PBX Core or Ring2All SBC Core).
Engine Architecture	Enum	Yes	ring2all_pbx	ring2all_pbx (Class 5 Ring2All Telephony Engine) or kalixor_sbc (Class 4 Kamailio SBC).
API Endpoint URL	URL	Yes	—	Base HTTPS URL where the remote node daemon is listening (e.g. https://192.168.10.31).
API Secret Key	Password	Yes	—	High-entropy authentication token sent via the X-API-Key HTTP header for administrative commands.
Deployment Environment	Enum	Yes	live	Target tier: live (production billing), staging, or sandbox.
Default Cluster Engine	Boolean	Yes	false	When true, new customer subscriptions are automatically provisioned on this node by default.
Active Status	Boolean	Yes	true	When active, the node receives automatic provisioning dispatches and health check pings.

---

5. Architectural Flow & Distributed Node Synchronization

          Customer Subscription Event
                       │
                       ▼
 ┌───────────────────────────────────────────┐
 │    Query Default Node for Service Type    │
 └─────────────────────┬─────────────────────┘
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
  Engine: ring2all_pbx        Engine: kalixor_sbc
         │                           │
         ▼                           ▼
 ┌─────────────────────────┐ ┌─────────────────────────┐
 │ POST /api/tenants       │ │ POST /api/sip-trunks    │
 │ Headers:                │ │ Headers:                │
 │   X-API-Key: <TOKEN>    │ │   X-API-Key: <TOKEN>    │
 │ Payload:                │ │ Payload:                │
 │   tenant_id: 104        │ │   customer_id: 104      │
 │   domain: voice.acme.com│ │   capacity: 20 channels │
 └─────────────────────────┘ └─────────────────────────┘

---

6. Common Scenarios & Operational Playbooks

Scenario A: Registering a New Ring2All SBC Core Node

1. Navigate to Telecom Providers → Telecom Nodes & Engines and click + Add.
2. Enter Node Name: Ring2All SBC Core Virginia.
3. Set Engine Architecture to Ring2All SBC (Class 4).
4. Enter API Endpoint URL: https://192.168.10.32.
5. Enter the pre-shared API Secret Key generated on the SBC server.
6. Toggle Default Cluster Engine to Yes if this SBC handles primary wholesale carrier transit.
7. Click Ping Test to verify TLS handshake and latency, then click Save Node.

Scenario B: Performing Zero-Downtime Node Maintenance

1. Prior to performing OS or kernel updates on a voice core server, locate the node in the DataGrid.
2. Toggle Active Status from Active to Inactive.
3. The platform automatically shifts all new incoming customer provisioning to secondary active nodes while leaving existing active calls on the server unaffected until scheduled drain completion.

---

7. Troubleshooting & Diagnostic Commands

Verifying Registered Telecom Nodes & Status (PostgreSQL)

su - postgres -c "psql -d ss_billing -c \"
SELECT id, name, node_type, host, port, is_active, is_default,
       last_sync_at, last_ping_status
FROM telecom_nodes
ORDER BY id ASC;\""

Testing Node Reachability & Latency via cURL

curl -s -k -w "\nHTTP Code: %{http_code}\nTotal Time: %{time_total}s\n" \
  https://192.168.10.31/health

---

8. Model Context Protocol (MCP) AI Integration

The Telecom Engines & Infrastructure Nodes module connects directly to the Ring2All BSS MCP Server, providing NOC engineers and automated infrastructure copilots with real-time visibility into telephony node health and orchestration status.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
list_telecom_nodes_status	Telecom & Carrier Engineer / Admin	Lists telephony core switching engines (Ring2All PBX, Ring2All SBC) with health status, ping metrics, and active flag.	{}
sync_telecom_node	Super Administrator	Triggers configuration resynchronization or health ping against a specific telecom node engine.	{"nodeId": 1}
diagnose_telecom_node_sync	Telecom & Carrier Engineer / Admin	Verifies end-to-end API connectivity, TLS handshakes, and node heartbeats between BSS and voice switches.	{}
diagnose_ocs_realtime_pipeline	Telecom & Carrier Engineer / Admin	Deep diagnostic of the online charging pipeline: database latency, customer balances, active rate cards, and registered voice nodes.	{}

Sample MCP Tool Execution: list_telecom_nodes_status

Request Payload

{
  "name": "list_telecom_nodes_status",
  "arguments": {}
}

Response Payload

[
  {
    "id": 1,
    "name": "Primary SBC Core",
    "nodeType": "kalixor_sbc",
    "host": "192.168.10.31",
    "port": 443,
    "isActive": true,
    "isDefault": true,
    "lastSyncAt": "2026-09-09T05:00:12Z",
    "lastPingStatus": "online",
    "lastPingLatencyMs": 4
  },
  {
    "id": 2,
    "name": "Primary PBX Cluster",
    "nodeType": "ring2all_pbx",
    "host": "192.168.10.30",
    "port": 443,
    "isActive": true,
    "isDefault": true,
    "lastSyncAt": "2026-09-09T05:00:14Z",
    "lastPingStatus": "online",
    "lastPingLatencyMs": 6
  }
]

Conversational AI Prompts for Copilot

• “Check the health status and round-trip ping latency for all telecom nodes.”
• “Run a complete diagnostic on the real-time OCS charging engine and connected voice switches.”
• “Is the Primary SBC Core node currently online and synchronized?”
• “Trigger an immediate sync against telecom node 1.”

---

9. Glossary

• Class 4 SBC: Carrier-grade network switch optimized for high-volume wholesale SIP transit, protocol normalization, and LCR routing.
• Class 5 PBX: Enterprise-facing switch providing end-user features like voicemail, IVR, queues, ring groups, and extension registration.
• X-API-Key: HTTP security header used to authenticate machine-to-machine REST communication between the billing engine and voice nodes.
• Node Orchestration: Automated synchronization ensuring accounts created in the billing system exist identically in the voice switching plane.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.