# signalapp/signal-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/signalapp/signal-desktop
- Repository: https://github.com/signalapp/signal-desktop

## Overview

Signal Desktop is a private desktop messaging client that also supports linked devices, group/direct calling, attachments, and synchronized account state. The principal workflow is user interaction with the desktop UI, which dispatches messaging or calling actions, updates local state, and presents results or notifications. Sampled code most directly establishes the calling orchestration and storage-sync paths; messaging, backup, and platform internals are represented only at supported directory boundaries because their implementations were not sampled.

Main entry points: [`ts/components/CallManager.dom.tsx`](https://github.com/signalapp/signal-desktop/blob/main/ts/components/CallManager.dom.tsx) (Call Manager), [`ts/services/storage.preload.ts`](https://github.com/signalapp/signal-desktop/blob/main/ts/services/storage.preload.ts) (Storage Operations), [`ts`](https://github.com/signalapp/signal-desktop/tree/main/ts) (Messaging Runtime), [`ts/textsecure/Storage.preload.ts`](https://github.com/signalapp/signal-desktop/blob/main/ts/textsecure/Storage.preload.ts) (Storage Facade)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_app_shell["Desktop App Shell<br/>[main.main.ts]"]
  node_conversation_ui["Conversation UI<br/>[ChatsTab.dom.tsx]"]
  node_messaging_runtime["Messaging Runtime"]
end

subgraph group_calling["Calling"]
  node_call_manager["Call Manager"]
  node_smart_call_manager["Smart Call Manager"]
  node_calling_engine["Calling Engine"]
  node_call_link_support["Call Link Support"]
end

subgraph group_state["State and Sync"]
  node_storage_facade["Storage Facade<br/>[Storage.preload.ts]"]
  node_storage_operations["Storage Operations<br/>[storage.preload.ts]"]
  node_record_conversion["Record Conversion"]
  node_local_database[("Local Database")]
  node_storage_protocol["Storage Protocol"]
end

subgraph group_platform["Platform Services"]
  node_attachments["Attachment Handling"]
  node_crypto["Cryptographic Services<br/>[Crypto.node.ts]"]
  node_notifications["Desktop Notifications"]
end

node_desktop_user(("Desktop User"))
node_signal_service["Signal Service"]
node_linked_device["Linked Mobile Device"]

node_desktop_user -->|"uses"| node_app_shell
node_desktop_user -->|"composes messages"| node_conversation_ui
node_desktop_user -->|"controls calls"| node_call_manager
node_conversation_ui -->|"dispatches messages"| node_messaging_runtime
node_messaging_runtime -->|"handles media"| node_attachments
node_messaging_runtime -->|"reads state"| node_storage_facade
node_smart_call_manager -->|"renders"| node_call_manager
node_smart_call_manager -->|"binds call actions"| node_calling_engine
node_call_manager -->|"starts or cancels"| node_calling_engine
node_call_manager -->|"builds call links"| node_call_link_support
node_call_manager -->|"triggers policy"| node_notifications
node_storage_facade -->|"reads and writes"| node_local_database
node_storage_operations -->|"converts records"| node_record_conversion
node_storage_operations -->|"syncs records"| node_signal_service
node_record_conversion -->|"encodes records"| node_storage_protocol
node_storage_operations -->|"updates state"| node_storage_facade
node_attachments -->|"protects media"| node_crypto
node_linked_device -->|"links and syncs"| node_signal_service

click node_app_shell "https://github.com/signalapp/signal-desktop/blob/main/app/main.main.ts"
click node_conversation_ui "https://github.com/signalapp/signal-desktop/blob/main/ts/components/ChatsTab.dom.tsx"
click node_messaging_runtime "https://github.com/signalapp/signal-desktop/tree/main/ts"
click node_call_manager "https://github.com/signalapp/signal-desktop/blob/main/ts/components/CallManager.dom.tsx"
click node_smart_call_manager "https://github.com/signalapp/signal-desktop/blob/main/ts/state/smart/CallManager.preload.tsx"
click node_calling_engine "https://github.com/signalapp/signal-desktop/tree/main/ts/calling"
click node_call_link_support "https://github.com/signalapp/signal-desktop/blob/main/ts/util/callLinkRootKeyToUrl.std.ts"
click node_storage_facade "https://github.com/signalapp/signal-desktop/blob/main/ts/textsecure/Storage.preload.ts"
click node_storage_operations "https://github.com/signalapp/signal-desktop/blob/main/ts/services/storage.preload.ts"
click node_record_conversion "https://github.com/signalapp/signal-desktop/blob/main/ts/services/storageRecordOps.preload.ts"
click node_local_database "https://github.com/signalapp/signal-desktop/blob/main/app/sql_channel.main.ts"
click node_storage_protocol "https://github.com/signalapp/signal-desktop/blob/main/protos/SignalStorage.proto"
click node_attachments "https://github.com/signalapp/signal-desktop/blob/main/app/attachments.node.ts"
click node_crypto "https://github.com/signalapp/signal-desktop/blob/main/ts/Crypto.node.ts"
click node_notifications "https://github.com/signalapp/signal-desktop/blob/main/app/WindowsNotifications.main.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_app_shell,node_conversation_ui,node_messaging_runtime,node_desktop_user toneBlue
class node_call_manager,node_smart_call_manager,node_calling_engine,node_call_link_support toneAmber
class node_storage_facade,node_storage_operations,node_record_conversion,node_local_database,node_storage_protocol toneMint
class node_attachments,node_crypto,node_notifications toneRose
class node_signal_service,node_linked_device toneIndigo
```

## Components

### User Experience

- [Desktop App Shell](https://github.com/signalapp/signal-desktop/blob/main/app/main.main.ts): `app/main.main.ts`
- [Conversation UI](https://github.com/signalapp/signal-desktop/blob/main/ts/components/ChatsTab.dom.tsx): `ts/components/ChatsTab.dom.tsx`
- [Messaging Runtime](https://github.com/signalapp/signal-desktop/tree/main/ts): `ts`

### Calling

- [Call Manager](https://github.com/signalapp/signal-desktop/blob/main/ts/components/CallManager.dom.tsx): `ts/components/CallManager.dom.tsx`
- [Smart Call Manager](https://github.com/signalapp/signal-desktop/blob/main/ts/state/smart/CallManager.preload.tsx): `ts/state/smart/CallManager.preload.tsx`
- [Calling Engine](https://github.com/signalapp/signal-desktop/tree/main/ts/calling): `ts/calling`
- [Call Link Support](https://github.com/signalapp/signal-desktop/blob/main/ts/util/callLinkRootKeyToUrl.std.ts): `ts/util/callLinkRootKeyToUrl.std.ts`

### State and Sync

- [Storage Facade](https://github.com/signalapp/signal-desktop/blob/main/ts/textsecure/Storage.preload.ts): `ts/textsecure/Storage.preload.ts`
- [Storage Operations](https://github.com/signalapp/signal-desktop/blob/main/ts/services/storage.preload.ts): `ts/services/storage.preload.ts`
- [Record Conversion](https://github.com/signalapp/signal-desktop/blob/main/ts/services/storageRecordOps.preload.ts): `ts/services/storageRecordOps.preload.ts`
- [Local Database](https://github.com/signalapp/signal-desktop/blob/main/app/sql_channel.main.ts): `app/sql_channel.main.ts`
- [Storage Protocol](https://github.com/signalapp/signal-desktop/blob/main/protos/SignalStorage.proto): `protos/SignalStorage.proto`

### Platform Services

- [Attachment Handling](https://github.com/signalapp/signal-desktop/blob/main/app/attachments.node.ts): `app/attachments.node.ts`
- [Cryptographic Services](https://github.com/signalapp/signal-desktop/blob/main/ts/Crypto.node.ts): `ts/Crypto.node.ts`
- [Desktop Notifications](https://github.com/signalapp/signal-desktop/blob/main/app/WindowsNotifications.main.ts): `app/WindowsNotifications.main.ts`

### Other components

- **Desktop User**
- **Signal Service**
- **Linked Mobile Device**

## Connections

- Desktop User → Desktop App Shell: uses
- Desktop User → Conversation UI: composes messages
- Desktop User → Call Manager: controls calls
- Conversation UI → Messaging Runtime: dispatches messages
- Messaging Runtime → Attachment Handling: handles media
- Messaging Runtime → Storage Facade: reads state
- Smart Call Manager → Call Manager: renders
- Smart Call Manager → Calling Engine: binds call actions
- Call Manager → Calling Engine: starts or cancels
- Call Manager → Call Link Support: builds call links
- Call Manager → Desktop Notifications: triggers policy
- Storage Facade → Local Database: reads and writes
- Storage Operations → Record Conversion: converts records
- Storage Operations → Signal Service: syncs records
- Record Conversion → Storage Protocol: encodes records
- Storage Operations → Storage Facade: updates state
- Attachment Handling → Cryptographic Services: protects media
- Linked Mobile Device → Signal Service: links and syncs
