Connection & Node Architecture

📖 Introduction

The Connection settings module controls the underlying networking topology connecting the Switchboard web client, the backend Fastify telemetry API (softswitch-monitoring-api), and the core Ring2All telephony engines (Telephony Event Socket (ESL) and PostgreSQL).

The architecture supports both Single-Server Standalone Installations and Multi-Node Distributed Deployments, enabling organizations to scale operator consoles independently of media gateways and database clusters.

---

🏗️ Operational Connection Modes

Mode	Topology Type	Network Architecture	Primary Use Case
Local Mode	Embedded PBX	Switchboard web frontend and monitoring-api run on the same physical or virtual server as Telephony Server. Communicates via Unix sockets or 127.0.0.1.	Small-to-medium single-server deployments, branch office appliances, and lab testing.
Remote Mode	Distributed Cluster	The Switchboard operator cluster runs on dedicated web edge nodes, communicating with a central Ring2All SoftSwitch cluster over secure HTTPS/WSS APIs.	Enterprise call centers, MSP multi-tenant clouds, high-availability clusters.

graph TD
    subgraph Edge Layer
        Operator[Operator Workstation] -->|HTTPS / WSS| WebNode[Switchboard Web Node]
    end

    subgraph Service Layer
        WebNode -->|REST / WebSocket| MonAPI[Monitoring API :3500]
        MonAPI -->|Admin REST API| AdminAPI[Ring2All Admin API :3000]
    end

    subgraph Telephony Core
        MonAPI -->|ESL TCP 8021| FS[Ring2All Telephony Engine]
        MonAPI -->|PostgreSQL 5432| DB[(Ring2All Database)]
        AdminAPI -->|PostgreSQL 5432| DB
    end

---

🔌 API Endpoints & Authentication

1. SoftSwitch Admin API (Remote Mode)

In distributed environments, the Switchboard node delegates tenant authentication, billing validation, and user directory queries to the central SoftSwitch API:

• Admin API URL: The FQDN of the primary management cluster (e.g., https://pbx.ring2all.com).
• API Token: A high-privilege application bearer token generated under PBX Administration > Application Keys.
• Connection Status: Real-time health badge (Connected, Disconnected, or Error).
• Test Connection: Triggers an on-demand HTTPS handshake verifying token validity and API reachability.

2. Monitoring Telemetry API

The telemetry service (monitoring-api) bridges low-level Telephony Event Socket (ESL) events into real-time WebSockets:

• Monitoring API URL: Default: http://localhost:3500 (Local Mode) or secure public endpoint https://monitoring.company.com.
• API Token: Optional mutual authentication token securing internal event bus endpoints.
• Diagnostics: Displays instantaneous ping latency and database pool connectivity.

---

🩺 Diagnostic Health Checks & Reconnection Policies

The console enforces intelligent resilience policies to survive network blips:

• Automatic Reconnection Backoff: If a network interruption occurs, the WebSocket engine attempts reconnection using an exponential backoff curve (1s, 2s, 5s, 10s, 30s).
• State Re-Synchronization: Upon reconnection, the client automatically executes an ESL snapshot fetch to reconcile any channel terminations or new incoming calls that occurred while offline.
• Last Checked Timestamp: Displays the exact timestamp of the last successful health check ping.