---
title: "Telecom Engines & Infrastructure Nodes Module Documentation"
description: "Documentation for Telecom Nodes & Engine"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial & Business Value)](#2-module-overview-commercial--business-value)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Form Structure](#4-visual-interface--form-structure)
5. [Architectural Flow & Distributed Node Synchronization](#5-architectural-flow--distributed-node-synchronization)
6. [Common Scenarios & Operational Playbooks](#6-common-scenarios--operational-playbooks)
7. [Troubleshooting & Diagnostic Commands](#7-troubleshooting--diagnostic-commands)
8. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
9. [Glossary](#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.

![Telecom Engines List View](/screenshots/billing/telecom-providers/telecom-nodes/telecom-nodes-list.png)

### 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.

![Telecom Engine Configuration Form](/screenshots/billing/telecom-providers/telecom-nodes/telecom-nodes-form.png)

### 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)
```bash
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
```bash
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
```json
{
  "name": "list_telecom_nodes_status",
  "arguments": {}
}
```

#### Response Payload
```json
[
  {
    "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.