---
title: "Connection & Node Architecture"
description: "Switchboard topology configuration, Local versus Remote modes, SoftSwitch Admin API integration, monitoring API telemetry sockets, and health diagnostics."
---

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

![Connection Settings](/screenshots/apps/switchboard/connection.png)

---

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

```mermaid
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.