# finos/symphonyelectron architecture

> Architecture diagram of the GitHub repository finos/symphonyelectron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/finos/symphonyelectron
- Repository: https://github.com/finos/symphonyelectron

## Overview

SymphonyElectron is a cross-platform Electron desktop wrapper for the Symphony Communication Platform. The principal workflow starts when a desktop user launches the app: the Electron main process initializes configuration and desktop facilities, then creates a window that loads the configured Symphony web client. The wrapper adds native window, menu, notification, presence, screen-capture, and update capabilities around that client; the hosted Symphony client is an external system, not code in this repository.

#### Components

##### Application lifecycle and windows
- **Desktop user** — *external; null repository path.* Launches and interacts with the installed desktop application.
- **Electron main-process bootstrap** — `src/app/main.ts`. Starts the app and coordinates initialization of configuration, windows, protocol handling, updates, and other desktop features.
- **Window orchestration** — `src/app/window-handler.ts`. Creates and manages the main and auxiliary Electron windows, loads the configured web client, and sends page-load information to its contents.
- **Window and native UI utilities** — `src/app/window-utils.ts`. Implements reusable window construction, locale updates, reachability checks, and supporting native-window behavior; the window handler calls its window-loading helpers.
- **Window actions** — `src/app/window-actions.ts`. Implements desktop window actions used alongside window orchestration.
- **Renderer UI and bridge** — `src/renderer/app-bridge.ts`. Renderer-side bridge entry point; the renderer tree also contains grouped UI for notifications, downloads, screen capture, authentication, and app status.
- **Symphony web client** — *external; null repository path.* The hosted client loaded into the desktop window; its server-side behavior is outside this repository.

##### Configuration, policy, and shared state
- **Configuration and platform settings** — `src/app/config-handler.ts`. Loads and exposes user, global, and cloud configuration used to control wrapper behavior.
- **URL whitelist policy** — `src/common/whitelist-handler.ts`. Parses hostnames and checks navigation URLs against configured whitelist entries.
- **Window and presence state** — `src/app/stores/window-store.ts`. Implements window-related state; the store index also constructs presence and menu stores.
- **IPC and desktop API contracts** — `src/common/api-interface.ts`. Defines command names, window types, and shared payload types for desktop capabilities.
- **Localization** — `src/common/i18n.ts`. Loads locale resources and formats translated strings.

##### Desktop capabilities
- **Main-process API and event handling** — `src/app/main-api-handler.ts`. Handles desktop API operations and connects them to capability-specific handlers; it imports the event handler and multiple feature modules.
- **Main-process event routing** — `src/app/main-event-handler.ts`. Implements main-process event handling used by desktop features.
- **Presence management** — `src/app/presence-status-handler.ts`. Implements presence operations using shared stores and window facilities.
- **Screen capture and annotation** — `src/app/screen-snippet-handler.ts`. Implements screen-snippet operations and uses window, store, and analytics modules.
- **Notifications** — `src/app/notifications/call-notification.ts`. Implements call-notification behavior across main-process windows and renderer notification UI.
- **Renderer notification handling** — `src/renderer/notification-handler.ts`. Implements renderer-side notification handling; the index lists the main-process call-notification module as a reference.
- **Auto-update** — `src/app/auto-update-handler.ts`. Selects platform updater implementations, checks update metadata, and handles update workflow and analytics.

##### Supporting product behavior
- **Analytics** — `src/app/bi/analytics-handler.ts`. Implements analytics handling using the shared event and payload definitions.
- **Windows installer** — `installer/win/WixSharpInstaller/Symphony.cs`. Implements the Windows installer; the installer source references its welcome, progress, exit, close, and maintenance dialogs.

#### Relationships

- **Desktop user -> Electron main-process bootstrap**: launches the desktop app; evidence: none (inferred from the documented desktop-client product).
- **Electron main-process bootstrap -> Configuration and platform settings**: initializes configuration as part of app startup; evidence: `src/app/main.ts` (SOURCE INDEX).
- **Electron main-process bootstrap -> Window orchestration**: starts window handling as part of app startup; evidence: `src/app/main.ts` (SOURCE INDEX).
- **Window orchestration -> Symphony web client**: loads the configured URL in Electron web contents; evidence: `src/app/window-handler.ts` (excerpt).
- **Window orchestration -> Window and native UI utilities**: loads web contents and injects window styling through helpers; evidence: `src/app/window-handler.ts` (excerpt).
- **Window orchestration -> Window actions**: uses window-action functionality; evidence: `src/app/window-handler.ts` (SOURCE INDEX).
- **Main-process API and event handling -> Configuration and platform settings**: imports configuration for desktop API behavior; evidence: `src/app/main-api-handler.ts` (SOURCE INDEX).
- **Main-process API and event handling -> Presence management**: imports presence handling; evidence: `src/app/main-api-handler.ts` (SOURCE INDEX).
- **Main-process API and event handling -> Screen capture and annotation**: imports screen-snippet handling; evidence: `src/app/main-api-handler.ts` (SOURCE INDEX).
- **Main-process API and event handling -> Main-process event routing**: imports the event handler; evidence: `src/app/main-api-handler.ts` (SOURCE INDEX).
- **Presence management -> Window and presence state**: accesses the shared store; evidence: `src/app/presence-status-handler.ts` (SOURCE INDEX).
- **Screen capture and annotation -> Window and presence state**: imports the window store; evidence: `src/app/screen-snippet-handler.ts` (SOURCE INDEX).
- **Screen capture and annotation -> Analytics**: imports analytics functionality; evidence: `src/app/screen-snippet-handler.ts` (SOURCE INDEX).
- **Auto-update -> Configuration and platform settings**: reads configuration while preparing update behavior; evidence: `src/app/auto-update-handler.ts` (SOURCE INDEX).
- **Configuration and platform settings -> Analytics**: sends install-completion analytics; evidence: `src/app/config-handler.ts` (excerpt).
- **Call-notification UI -> Renderer notification handling**: the renderer handler references the main-process call-notification module; evidence: `src/renderer/notification-handler.ts` (SOURCE INDEX).

#### Coverage limits

The sampled source does not establish all startup ordering, the complete IPC dispatch path between renderer and main process, or the Symphony server’s behavior. The renderer bridge and several substantial feature modules are present in the tree but were not excerpted, so their detailed wiring is not asserted. The README documents supported desktop platforms, but this map focuses on the sampled application workflow.

Main entry points: [`src/app/main-api-handler.ts`](https://github.com/finos/symphonyelectron/blob/main/src/app/main-api-handler.ts) (Main-process API), [`src/app/window-handler.ts`](https://github.com/finos/symphonyelectron/blob/main/src/app/window-handler.ts) (Window orchestration), [`src/app/config-handler.ts`](https://github.com/finos/symphonyelectron/blob/main/src/app/config-handler.ts) (Configuration settings), [`src/app/main.ts`](https://github.com/finos/symphonyelectron/blob/main/src/app/main.ts) (Electron main bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lifecycle["Application lifecycle"]
  node_desktop_user(("Desktop user<br/>External actor"))
  node_main_bootstrap["Electron main bootstrap<br/>Application entry point"]
  node_window_orchestration["Window orchestration<br/>Window management"]
  node_symphony_client["Symphony web client<br/>External system"]
  node_window_utilities["Window utilities<br/>Native window helpers"]
  node_window_actions["Window actions<br/>Desktop actions"]
end

subgraph group_shared["Configuration and shared state"]
  node_configuration["Configuration settings<br/>[config-handler.ts]"]
  node_window_state[("Window and presence state<br/>Shared store")]
end

subgraph group_capabilities["Desktop capabilities"]
  node_main_api["Main-process API<br/>Desktop API handler"]
  node_presence["Presence management<br/>Presence handler"]
  node_screen_capture["Screen capture<br/>Screen-snippet handler"]
  node_event_routing["Main-process event routing<br/>Event handler"]
  node_auto_update["Auto-update<br/>Update handler"]
  node_call_notifications["Call notifications<br/>Notification handler"]
  node_analytics["Analytics"]
end

subgraph group_renderer["Renderer notifications"]
  node_renderer_notifications["Renderer notification handling<br/>Notification handler"]
end

node_desktop_user -.->|"launches"| node_main_bootstrap
node_main_bootstrap -->|"initializes"| node_configuration
node_main_bootstrap -->|"starts"| node_window_orchestration
node_window_orchestration -->|"loads"| node_symphony_client
node_window_orchestration -->|"uses"| node_window_utilities
node_window_orchestration -->|"uses"| node_window_actions
node_main_api -->|"imports"| node_configuration
node_main_api -->|"imports"| node_presence
node_main_api -->|"imports"| node_screen_capture
node_main_api -->|"imports"| node_event_routing
node_presence -->|"accesses"| node_window_state
node_screen_capture -->|"imports"| node_window_state
node_screen_capture -->|"imports"| node_analytics
node_auto_update -->|"reads"| node_configuration
node_configuration -->|"sends"| node_analytics
node_call_notifications -->|"references"| node_renderer_notifications

click node_main_bootstrap "https://github.com/finos/symphonyelectron/blob/main/src/app/main.ts"
click node_window_orchestration "https://github.com/finos/symphonyelectron/blob/main/src/app/window-handler.ts"
click node_window_utilities "https://github.com/finos/symphonyelectron/blob/main/src/app/window-utils.ts"
click node_window_actions "https://github.com/finos/symphonyelectron/blob/main/src/app/window-actions.ts"
click node_configuration "https://github.com/finos/symphonyelectron/blob/main/src/app/config-handler.ts"
click node_window_state "https://github.com/finos/symphonyelectron/blob/main/src/app/stores/window-store.ts"
click node_main_api "https://github.com/finos/symphonyelectron/blob/main/src/app/main-api-handler.ts"
click node_presence "https://github.com/finos/symphonyelectron/blob/main/src/app/presence-status-handler.ts"
click node_screen_capture "https://github.com/finos/symphonyelectron/blob/main/src/app/screen-snippet-handler.ts"
click node_event_routing "https://github.com/finos/symphonyelectron/blob/main/src/app/main-event-handler.ts"
click node_auto_update "https://github.com/finos/symphonyelectron/blob/main/src/app/auto-update-handler.ts"
click node_call_notifications "https://github.com/finos/symphonyelectron/blob/main/src/app/notifications/call-notification.ts"
click node_analytics "https://github.com/finos/symphonyelectron/blob/main/src/app/bi/analytics-handler.ts"
click node_renderer_notifications "https://github.com/finos/symphonyelectron/blob/main/src/renderer/notification-handler.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop_user,node_main_bootstrap,node_window_orchestration,node_symphony_client,node_window_utilities,node_window_actions toneBlue
class node_configuration,node_window_state toneAmber
class node_main_api,node_presence,node_screen_capture,node_event_routing,node_auto_update,node_call_notifications,node_analytics toneMint
class node_renderer_notifications toneRose
```

## Components

### Application lifecycle

- **Desktop user**: External actor
- [Electron main bootstrap](https://github.com/finos/symphonyelectron/blob/main/src/app/main.ts): Application entry point · `src/app/main.ts`
- [Window orchestration](https://github.com/finos/symphonyelectron/blob/main/src/app/window-handler.ts): Window management · `src/app/window-handler.ts`
- **Symphony web client**: External system
- [Window utilities](https://github.com/finos/symphonyelectron/blob/main/src/app/window-utils.ts): Native window helpers · `src/app/window-utils.ts`
- [Window actions](https://github.com/finos/symphonyelectron/blob/main/src/app/window-actions.ts): Desktop actions · `src/app/window-actions.ts`

### Configuration and shared state

- [Configuration settings](https://github.com/finos/symphonyelectron/blob/main/src/app/config-handler.ts): Configuration · `src/app/config-handler.ts`
- [Window and presence state](https://github.com/finos/symphonyelectron/blob/main/src/app/stores/window-store.ts): Shared store · `src/app/stores/window-store.ts`

### Desktop capabilities

- [Main-process API](https://github.com/finos/symphonyelectron/blob/main/src/app/main-api-handler.ts): Desktop API handler · `src/app/main-api-handler.ts`
- [Presence management](https://github.com/finos/symphonyelectron/blob/main/src/app/presence-status-handler.ts): Presence handler · `src/app/presence-status-handler.ts`
- [Screen capture](https://github.com/finos/symphonyelectron/blob/main/src/app/screen-snippet-handler.ts): Screen-snippet handler · `src/app/screen-snippet-handler.ts`
- [Main-process event routing](https://github.com/finos/symphonyelectron/blob/main/src/app/main-event-handler.ts): Event handler · `src/app/main-event-handler.ts`
- [Auto-update](https://github.com/finos/symphonyelectron/blob/main/src/app/auto-update-handler.ts): Update handler · `src/app/auto-update-handler.ts`
- [Call notifications](https://github.com/finos/symphonyelectron/blob/main/src/app/notifications/call-notification.ts): Notification handler · `src/app/notifications/call-notification.ts`
- [Analytics](https://github.com/finos/symphonyelectron/blob/main/src/app/bi/analytics-handler.ts): Analytics handler · `src/app/bi/analytics-handler.ts`

### Renderer notifications

- [Renderer notification handling](https://github.com/finos/symphonyelectron/blob/main/src/renderer/notification-handler.ts): Notification handler · `src/renderer/notification-handler.ts`

## Connections

- Desktop user → Electron main bootstrap: launches · Inferred; not shown in the code that was read.
- Electron main bootstrap → Configuration settings: initializes (evidence: `src/app/main.ts`)
- Electron main bootstrap → Window orchestration: starts (evidence: `src/app/main.ts`)
- Window orchestration → Symphony web client: loads (evidence: `src/app/window-handler.ts`)
- Window orchestration → Window utilities: uses (evidence: `src/app/window-handler.ts`)
- Window orchestration → Window actions: uses (evidence: `src/app/window-handler.ts`)
- Main-process API → Configuration settings: imports (evidence: `src/app/main-api-handler.ts`)
- Main-process API → Presence management: imports (evidence: `src/app/main-api-handler.ts`)
- Main-process API → Screen capture: imports (evidence: `src/app/main-api-handler.ts`)
- Main-process API → Main-process event routing: imports (evidence: `src/app/main-api-handler.ts`)
- Presence management → Window and presence state: accesses (evidence: `src/app/presence-status-handler.ts`)
- Screen capture → Window and presence state: imports (evidence: `src/app/screen-snippet-handler.ts`)
- Screen capture → Analytics: imports (evidence: `src/app/screen-snippet-handler.ts`)
- Auto-update → Configuration settings: reads (evidence: `src/app/auto-update-handler.ts`)
- Configuration settings → Analytics: sends · Sends install-completion analytics. (evidence: `src/app/config-handler.ts`)
- Call notifications → Renderer notification handling: references (evidence: `src/renderer/notification-handler.ts`)
