# salesforce-misc/byo-demo-connector architecture

> Architecture diagram of the GitHub repository salesforce-misc/byo-demo-connector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/salesforce-misc/byo-demo-connector
- Repository: https://github.com/salesforce-misc/byo-demo-connector

## Overview

##### Main Components
a. Frontend (Browser UI)
- Static HTML pages in `/public` (e.g. `app.html`, `ccaas.html`, `ottapp.html`, `remote.html`, etc.)
- Bundled JavaScript modules built by Webpack:
- src/login – handles authentication UI
- src/byo-ott-app – OTT (Messaging) UI logic
- src/remote-control – Voice simulation UI logic
- src/common – shared constants and utils
- src/main/connector.js & src/main/vendor-sdk.js – core connector logic injected into the page
- src/hid – optional USB‐HID device integration (Jabra, Plantronics parsers)

b. Backend (Node.js Server)
- Entry point: `src/server/server.mjs`
- Authentication & Salesforce API layer:
- `src/server/ottAppLib/sfdc-auth.mjs` – JWT/OAuth2 handshake
- `src/server/ottAppLib/pubsub_api.proto` + `sfdc-pub-sub-api.mjs` – Pub/Sub streaming
- Voice Connector:
- `src/server/scrtConnector.mjs` – interfaces with SCRT2 telephony service
- `src/server/ottAppServer.mjs` – HTTP endpoints for voice simulation
- Utilities & configuration: messaging constants, certs (private.key, cert.pem), env var loader

c. Apex Mock Server (Salesforce Code)
- `/src/apex` folder contains Salesforce Apex classes & tests that mock a telephony API
- Deployed to a test Salesforce org to simulate Service Cloud Voice behavior

d. Salesforce Cloud Services (External)
- OAuth2 Token Endpoint (login.salesforce.com, test.salesforce.com, or custom dev instance)
- Service Cloud Voice/SCRT2 telephony integration service
- Service Cloud Messaging Pub/Sub endpoint (`api.pubsub.salesforce.com:7443`)

e. Build & Deployment Pipeline
- Webpack (`webpack.config.js`) – bundles the frontend assets, enables HTTPS dev server
- Gulp (`gulpfile.js`) – `bundle` tasks for production/minified connector
- Jest (`jest-report`) – unit tests for server & vendor-sdk
- Jenkinsfile – CI/CD orchestration

##### Relationships & Data Flows
- Browser UI ←HTTPS→ Node.js Server
- Voice Tab UI calls `/voice` endpoints on server for making/answering calls
- Messaging Tab UI uses vendor-SDK to subscribe/publish messages via server
- Node.js Server ←→ Salesforce
- OAuth2 handshake to obtain access token
- Pub/Sub subscription to receive inbound messages
- SCRT2 connector to post voice events & receive telephony callbacks
- Node.js Server ←→ Apex Mocks (deployed in Salesforce)
- Simulated telephony API endpoints for Partner Telephony demo
- Optional: Browser UI ←→ USB HID devices via `src/hid`

##### Architectural Patterns & Principles
- Modular separation: distinct folders for UI modules (byo-ott, remote-control), server support libs (`ottAppLib`), mock apex code
- Connector pattern: a thin client‐side connector that delegates all heavy lifting to the Node server
- Single Page App served by Webpack Dev Server over HTTPS for CORS compliance
- Secure JWT/OAuth flows with private/public key (self-signed cert for local dev)

##### Technologies & Frameworks
- Node.js (ESM `.mjs` modules)
- Webpack & webpack-dev-server (HTTPS, hot reload)
- Gulp for bundling
- Jest for unit testing
- JSDoc (`/docs`) for API documentation
- Salesforce Pub/Sub gRPC-style `.proto` integration
- Apex classes in Salesforce compiler/meta XML

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Browser UI" 
        direction TB
        StaticPages["Static Pages (/public)"]:::frontend
        subgraph "UI Modules"
            direction TB
            AuthUI["Login UI"]:::frontend
            OTTUI["OTT Messaging UI"]:::frontend
            VoiceUI["Voice Simulation UI"]:::frontend
            CommonUtils["Shared Constants & Utils"]:::frontend
            ConnectorLogic["Core Connector Logic"]:::frontend
            VendorSDK["Vendor SDK"]:::frontend
            USBHID["USB-HID Integration"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "Node.js Server" 
        direction TB
        EntryPoint["server.mjs (Entry Point)"]:::backend
        subgraph "Auth & SFDC API"
            direction TB
            SfdcAuth["sfdc-auth.mjs"]:::backend
            PubSubProto["pubsub_api.proto"]:::backend
            PubSubAPI["sfdc-pub-sub-api.mjs"]:::backend
        end
        subgraph "Voice Connector"
            direction TB
            SCRTConnector["scrtConnector.mjs"]:::backend
            OTTAppServer["ottAppServer.mjs"]:::backend
        end
        subgraph "Utils & Config"
            direction TB
            MsgConsts["messagingConstants.mjs"]:::backend
            Util["util.mjs"]:::backend
            Certs["cert.pem / private.key"]:::backend
        end
    end

    %% External Services
    OAuth["Salesforce OAuth2 Endpoint"]:::external
    PubSubSvc["SFDC Pub/Sub (port 7443)"]:::external
    SCRT2["SCRT2 Telephony Service"]:::external

    %% Apex Mock Server
    ApexMock["Apex Mock Server"]:::apex

    %% Build & Deployment Pipeline
    subgraph "Build & Deployment Pipeline"
        direction TB
        Webpack["Webpack"]:::pipeline
        Gulp["Gulp"]:::pipeline
        Jest["Jest Tests"]:::pipeline
        Jenkins["Jenkins CI/CD"]:::pipeline
    end

    %% Data Flows
    StaticPages -->|HTTPS:8080| EntryPoint
    AuthUI -->|HTTPS:8080| EntryPoint
    OTTUI -->|HTTPS:8080| EntryPoint
    VoiceUI -->|HTTPS:8080| EntryPoint
    CommonUtils --> ConnectorLogic
    ConnectorLogic -->|delegates API calls| EntryPoint
    VendorSDK -->|pub/sub via server| EntryPoint
    USBHID -->|optional HID| VoiceUI

    EntryPoint -->|OAuth2 handshake| SfdcAuth
    SfdcAuth -->|access token| EntryPoint
    EntryPoint -->|gRPC pub/sub| PubSubAPI
    PubSubProto --> PubSubAPI
    EntryPoint -->|HTTP endpoints| OTTAppServer
    EntryPoint -->|SCRT2 API calls| SCRTConnector
    SCRTConnector --> SCRT2
    EntryPoint -->|Pub/Sub subscribe/publish| PubSubSvc
    EntryPoint -->|Calls mock telephony| ApexMock

    %% Pipeline Flow
    Webpack --> Gulp --> Jest --> Jenkins

    %% Click Events - Frontend
    click StaticPages "https://github.com/salesforce-misc/byo-demo-connector/tree/main/public"
    click AuthUI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/login/index.js"
    click OTTUI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/byo-ott-app/index.js"
    click OTTUI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/byo-ott-app/main.js"
    click VoiceUI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/remote-control/index.js"
    click VoiceUI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/remote-control/main.js"
    click CommonUtils "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/common/constants.js"
    click CommonUtils "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/common/healthCheckConstants.js"
    click CommonUtils "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/common/messagingConstants.js"
    click ConnectorLogic "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/main/connector.js"
    click ConnectorLogic "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/main/index.js"
    click VendorSDK "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/main/vendor-sdk.js"
    click USBHID "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/hid/hidDeviceHandler.js"
    click USBHID "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/hid/hidDeviceParser.js"
    click USBHID "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/hid/hidDeviceParserFactory.js"
    click USBHID "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/hid/jabraHIDDeviceParser.js"
    click USBHID "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/hid/plantronicsHIDDeviceParser.js"

    %% Click Events - Backend
    click EntryPoint "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/server.mjs"
    click SfdcAuth "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/ottAppLib/sfdc-auth.mjs"
    click PubSubProto "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/ottAppLib/pubsub_api.proto"
    click PubSubAPI "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/ottAppLib/sfdc-pub-sub-api.mjs"
    click SCRTConnector "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/scrtConnector.mjs"
    click OTTAppServer "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/ottAppServer.mjs"
    click MsgConsts "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/messagingConstants.mjs"
    click Util "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/util.mjs"
    click Certs "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/cert.pem"
    click Certs "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/server/private.key"

    %% Click Events - Apex
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/QueueManagementMockServer.cls"
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/QueueManagementMockServer.cls-meta.xml"
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/QueueManagementMockServerTest.cls"
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/SampleQueueManagementImpl.cls"
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/SampleQueueManagementImpl.cls-meta.xml"
    click ApexMock "https://github.com/salesforce-misc/byo-demo-connector/blob/main/src/apex/SampleQueueMgmtImplTest.cls"

    %% Click Events - Pipeline
    click Webpack "https://github.com/salesforce-misc/byo-demo-connector/blob/main/webpack.config.js"
    click Gulp "https://github.com/salesforce-misc/byo-demo-connector/blob/main/gulpfile.js"
    click Jest "https://github.com/salesforce-misc/byo-demo-connector/blob/main/jest-report/index.html"
    click Jenkins "https://github.com/salesforce-misc/byo-demo-connector/tree/main/Jenkinsfile"

    %% Styles
    classDef frontend fill:#B3D4FC,stroke:#0366D6,stroke-width:1px
    classDef backend fill:#C6F6D5,stroke:#22863A,stroke-width:1px
    classDef external fill:#FEDC97,stroke:#B08900,stroke-width:1px
    classDef apex fill:#FDD8B0,stroke:#B31D28,stroke-width:1px
    classDef pipeline fill:#E2E8F0,stroke:#4A5568,stroke-width:1px
```
