# infomaniak/desktop-kdrive architecture

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

- Interactive diagram: https://gitdiagram.com/infomaniak/desktop-kdrive
- Repository: https://github.com/infomaniak/desktop-kdrive

## Overview

#### Purpose and executables
kDrive is a cross-platform desktop client for synchronizing local folders with Infomaniak kDrive, including sharing, conflict handling, selective sync, and on-demand files (“LiteSync”). The primary C++/Qt daemon entry point is `src/server/mainserver.cpp`; the legacy Qt GUI starts at `src/gui/mainclient.cpp`. A separate manual update executable starts at `src/manualupdater/main.cpp`. New native GUIs coexist for macOS and Windows.

#### Process topology and IPC boundary
The sync server is the authoritative local process: it owns accounts, sync configuration, databases, engine lifecycle, updates, and OS integrations. `src/server/appserver.cpp` composes this runtime. GUI requests cross an explicit local communications layer via `src/server/comm/commmanager.cpp` and GUI job dispatchers under `src/server/comm/guijobs/`. Transports are platform-dependent—pipes/sockets on general platforms and XPC on macOS (`src/server/comm/xpccommserver_mac.mm`). GUI clients receive asynchronous state, progress, error, and updater signals rather than directly manipulating engine state.

#### Synchronization engine
`src/libsyncengine` implements the Syncpal-based pipeline. Local filesystem changes are watched and normalized into operations by `src/libsyncengine/update_detection/file_system_observer/filesystemobserverworker.cpp`; remote state is represented through snapshots and update trees in `src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp`. Reconciliation detects/resolves conflicts and generates sync operations (`src/libsyncengine/reconciliation/conflict_finder/conflictfinderworker.cpp`, `src/libsyncengine/reconciliation/operation_generator/operationgeneratorworker.cpp`). Operations are dependency-sorted, then executed locally or remotely (`src/libsyncengine/propagation/operation_sorter/operationsorterworker.cpp`, `src/libsyncengine/propagation/executor/executorworker.cpp`). `src/libsyncengine/syncpal/syncpalworker.cpp` coordinates these stages per synchronization.

#### Persistence, credentials, and network boundary
SQLite-backed local state is split by concern: generic DB primitives in `src/libcommonserver/db/sqlitedb.cpp`, application parameters and folder rules in `src/libparms/db/parmsdb.cpp`, and sync-node state in `src/libsyncengine/db/syncdb.cpp`. Authentication tokens are isolated behind keychain storage in `src/libcommonserver/keychainmanager/keychainmanager.cpp`. The engine accesses Infomaniak login and kDrive HTTP APIs through typed network jobs, including cursor/long-poll remote listing (`src/libsyncengine/jobs/network/kDrive_API/listing/longpolljob.cpp`) and resumable upload sessions (`src/libsyncengine/jobs/network/kDrive_API/upload/upload_session/driveuploadsession.cpp`). Poco/OpenSSL form the transport/TLS runtime.

#### User interfaces
The legacy desktop GUI is Qt Widgets and communicates through `src/libcommongui/commclient.cpp`, with application coordination in `src/gui/clientgui.cpp`. Native GUI4 clients are separate consumers of the same server contract: macOS uses Swift/SwiftUI/AppKit beginning at `src/gui4/macOS/kDrive/KDriveApp.swift`, while Windows uses C#/XAML beginning at `src/gui4/windows/kDrive client/kDrive client/App.xaml.cs`. The macOS client explicitly models IPC queries, signals, and observable cache state in `src/gui4/macOS/kDriveCore/ServerBridge/XPC/` and `src/gui4/macOS/kDriveCore/ServerBridge/Cache/`.

#### Virtual files and file-manager integration
LiteSync exposes cloud content on demand rather than fully materializing it. Server-side VFS plugins are selected per OS (`src/server/vfs/mac/vfs_mac.cpp`, `src/server/vfs/win/vfs_win.cpp`). macOS Finder and LiteSync extensions communicate over XPC (`extensions/MacOSX/kDriveLiteSync/Extension/xpcService.m`); Windows implements Cloud Files API provider, placeholders, and Explorer extension components (`extensions/windows/cfapi/Vfs/cloudprovider.cpp`, `extensions/windows/cfapi/Vfs/placeholders.cpp`). These are privileged OS boundaries separate from the sync daemon.

#### Operations and delivery
The C++ core builds through CMake (`CMakeLists.txt`, `src/CMakeLists.txt`) with Conan-managed dependencies (`conanfile.py`). Supported runtime targets are Linux, macOS, and Windows; Qt underpins legacy UI and core process functionality, while native GUI4 adds Swift and .NET runtimes. Updates are server-managed with platform implementations (`src/server/updater/updatemanager.cpp`, `src/server/updater/sparkleupdater.mm`, `src/server/updater/windowsupdater.cpp`), plus a fallback/manual updater. Observability uses log4cplus, support-log upload jobs, Sentry (`src/libcommon/log/sentry/handler.cpp`), and Matomo clients.

Main entry points: [`src/server/appserver.cpp`](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/appserver.cpp) (Sync server), [`src/server/comm/commmanager.cpp`](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/comm/commmanager.cpp) (Local comm manager), [`src/libsyncengine/syncpal/syncpalworker.cpp`](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/syncpal/syncpalworker.cpp) (Syncpal coordinator), [`src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp`](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp) (Remote state detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Desktop clients"]
  node_legacy_gui["Legacy Qt GUI<br/>Qt Widgets client<br/>[clientgui.cpp]"]
  node_gui_comm_client["GUI comm client<br/>IPC client<br/>[commclient.cpp]"]
  node_mac_gui["macOS GUI4<br/>SwiftUI client<br/>[KDriveApp.swift]"]
  node_windows_gui["Windows GUI4<br/>C&#35;/XAML client<br/>[App.xaml.cs]"]
end

subgraph group_server["Sync server"]
  node_sync_server{{"Sync server<br/>authoritative daemon<br/>[appserver.cpp]"}}
  node_server_entry["Server entry point<br/>C++ executable<br/>[mainserver.cpp]"]
  node_comm_manager["Local comm manager<br/>IPC boundary<br/>[commmanager.cpp]"]
  node_xpc_server["macOS XPC server<br/>XPC transport"]
  node_updater["Update manager<br/>server update service<br/>[updatemanager.cpp]"]
  node_manual_updater["Manual updater<br/>fallback executable<br/>[main.cpp]"]
end

subgraph group_engine["Sync engine"]
  node_syncpal{{"Syncpal coordinator<br/>per-sync pipeline<br/>[syncpalworker.cpp]"}}
  node_change_detection["Change detection<br/>filesystem observer"]
  node_remote_state["Remote state detection<br/>update tree"]
  node_reconciliation["Reconciliation<br/>conflict &amp; operation generation"]
  node_execution["Operation execution<br/>sorted local/remote executor<br/>[executorworker.cpp]"]
end

subgraph group_platform["Platform &amp; cloud"]
  node_local_state[("Local SQLite state<br/>parameters and sync databases<br/>[syncdb.cpp]")]
  node_credentials["Keychain tokens<br/>credential store"]
  node_kdrive_api{{"Infomaniak APIs<br/>HTTP cloud boundary<br/>[longpolljob.cpp]"}}
  node_vfs_plugins["LiteSync VFS<br/>OS-specific virtual filesystem<br/>[vfs_mac.cpp]"]
  node_os_extensions["File-manager extensions<br/>privileged OS integration<br/>[cloudprovider.cpp]"]
  node_observability["Observability<br/>logs, support upload, Sentry<br/>[handler.cpp]"]
end

node_server_entry -->|"starts"| node_sync_server
node_legacy_gui -->|"uses"| node_gui_comm_client
node_gui_comm_client -->|"local requests &amp; signals"| node_comm_manager
node_mac_gui -->|"XPC queries &amp; signals"| node_xpc_server
node_windows_gui -->|"server contract"| node_comm_manager
node_comm_manager -->|"dispatches GUI jobs"| node_sync_server
node_xpc_server -->|"macOS transport"| node_comm_manager
node_sync_server -->|"manages sync lifecycle"| node_syncpal
node_sync_server -->|"accounts and folder rules"| node_local_state
node_sync_server -->|"reads tokens"| node_credentials
node_sync_server -->|"manages updates"| node_updater
node_updater -.->|"fallback path"| node_manual_updater
node_sync_server -->|"selects by OS"| node_vfs_plugins
node_vfs_plugins -->|"on-demand file integration"| node_os_extensions
node_syncpal -->|"local changes"| node_change_detection
node_syncpal -->|"remote snapshots"| node_remote_state
node_change_detection -->|"normalized operations"| node_reconciliation
node_remote_state -->|"update tree"| node_reconciliation
node_reconciliation -->|"conflicts resolved; operations generated"| node_execution
node_execution -->|"persists sync nodes"| node_local_state
node_execution -->|"downloads and uploads"| node_kdrive_api
node_remote_state -->|"long-poll listing"| node_kdrive_api
node_sync_server -->|"logs and reports"| node_observability

click node_legacy_gui "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui/clientgui.cpp"
click node_gui_comm_client "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommongui/commclient.cpp"
click node_mac_gui "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui4/macOS/kDrive/KDriveApp.swift"
click node_windows_gui "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui4/windows/kDrive%20client/kDrive%20client/App.xaml.cs"
click node_sync_server "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/appserver.cpp"
click node_server_entry "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/mainserver.cpp"
click node_comm_manager "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/comm/commmanager.cpp"
click node_xpc_server "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/comm/xpccommserver_mac.mm"
click node_updater "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/updater/updatemanager.cpp"
click node_manual_updater "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/manualupdater/main.cpp"
click node_syncpal "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/syncpal/syncpalworker.cpp"
click node_change_detection "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/update_detection/file_system_observer/filesystemobserverworker.cpp"
click node_remote_state "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp"
click node_reconciliation "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/reconciliation/conflict_finder/conflictfinderworker.cpp"
click node_execution "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/propagation/executor/executorworker.cpp"
click node_local_state "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/db/syncdb.cpp"
click node_credentials "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommonserver/keychainmanager/keychainmanager.cpp"
click node_kdrive_api "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/jobs/network/kDrive_API/listing/longpolljob.cpp"
click node_vfs_plugins "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/vfs/mac/vfs_mac.cpp"
click node_os_extensions "https://github.com/infomaniak/desktop-kdrive/blob/develop/extensions/windows/cfapi/Vfs/cloudprovider.cpp"
click node_observability "https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommon/log/sentry/handler.cpp"

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_legacy_gui,node_gui_comm_client,node_mac_gui,node_windows_gui toneBlue
class node_sync_server,node_server_entry,node_comm_manager,node_xpc_server,node_updater,node_manual_updater toneAmber
class node_syncpal,node_change_detection,node_remote_state,node_reconciliation,node_execution toneMint
class node_local_state,node_credentials,node_kdrive_api,node_vfs_plugins,node_os_extensions,node_observability toneRose
```

## Components

### Desktop clients

- [Legacy Qt GUI](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui/clientgui.cpp): Qt Widgets client · `src/gui/clientgui.cpp`
- [GUI comm client](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommongui/commclient.cpp): IPC client · `src/libcommongui/commclient.cpp`
- [macOS GUI4](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui4/macOS/kDrive/KDriveApp.swift): SwiftUI client · `src/gui4/macOS/kDrive/KDriveApp.swift`
- [Windows GUI4](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/gui4/windows/kDrive%20client/kDrive%20client/App.xaml.cs): C#/XAML client · `src/gui4/windows/kDrive client/kDrive client/App.xaml.cs`

### Sync server

- [Sync server](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/appserver.cpp): authoritative daemon · Owns accounts, sync configuration, engines, updates, and OS integration. · `src/server/appserver.cpp`
- [Server entry point](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/mainserver.cpp): C++ executable · `src/server/mainserver.cpp`
- [Local comm manager](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/comm/commmanager.cpp): IPC boundary · `src/server/comm/commmanager.cpp`
- [macOS XPC server](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/comm/xpccommserver_mac.mm): XPC transport · `src/server/comm/xpccommserver_mac.mm`
- [Update manager](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/updater/updatemanager.cpp): server update service · `src/server/updater/updatemanager.cpp`
- [Manual updater](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/manualupdater/main.cpp): fallback executable · `src/manualupdater/main.cpp`

### Sync engine

- [Syncpal coordinator](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/syncpal/syncpalworker.cpp): per-sync pipeline · `src/libsyncengine/syncpal/syncpalworker.cpp`
- [Change detection](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/update_detection/file_system_observer/filesystemobserverworker.cpp): filesystem observer · `src/libsyncengine/update_detection/file_system_observer/filesystemobserverworker.cpp`
- [Remote state detection](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp): update tree · `src/libsyncengine/update_detection/update_detector/updatetreeworker.cpp`
- [Reconciliation](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/reconciliation/conflict_finder/conflictfinderworker.cpp): conflict & operation generation · `src/libsyncengine/reconciliation/conflict_finder/conflictfinderworker.cpp`
- [Operation execution](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/propagation/executor/executorworker.cpp): sorted local/remote executor · `src/libsyncengine/propagation/executor/executorworker.cpp`

### Platform & cloud

- [Local SQLite state](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/db/syncdb.cpp): parameters and sync databases · `src/libsyncengine/db/syncdb.cpp`
- [Keychain tokens](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommonserver/keychainmanager/keychainmanager.cpp): credential store · `src/libcommonserver/keychainmanager/keychainmanager.cpp`
- [Infomaniak APIs](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libsyncengine/jobs/network/kDrive_API/listing/longpolljob.cpp): HTTP cloud boundary · Login, kDrive listing/long-poll, and resumable upload APIs. · `src/libsyncengine/jobs/network/kDrive_API/listing/longpolljob.cpp`
- [LiteSync VFS](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/server/vfs/mac/vfs_mac.cpp): OS-specific virtual filesystem · `src/server/vfs/mac/vfs_mac.cpp`
- [File-manager extensions](https://github.com/infomaniak/desktop-kdrive/blob/develop/extensions/windows/cfapi/Vfs/cloudprovider.cpp): privileged OS integration · Finder/XPC extension on macOS and Cloud Files provider on Windows. · `extensions/windows/cfapi/Vfs/cloudprovider.cpp`
- [Observability](https://github.com/infomaniak/desktop-kdrive/blob/develop/src/libcommon/log/sentry/handler.cpp): logs, support upload, Sentry · `src/libcommon/log/sentry/handler.cpp`

## Connections

- Server entry point → Sync server: starts
- Legacy Qt GUI → GUI comm client: uses
- GUI comm client → Local comm manager: local requests & signals
- macOS GUI4 → macOS XPC server: XPC queries & signals
- Windows GUI4 → Local comm manager: server contract
- Local comm manager → Sync server: dispatches GUI jobs
- macOS XPC server → Local comm manager: macOS transport
- Sync server → Syncpal coordinator: manages sync lifecycle
- Sync server → Local SQLite state: accounts and folder rules
- Sync server → Keychain tokens: reads tokens
- Sync server → Update manager: manages updates
- Update manager → Manual updater: fallback path
- Sync server → LiteSync VFS: selects by OS
- LiteSync VFS → File-manager extensions: on-demand file integration
- Syncpal coordinator → Change detection: local changes
- Syncpal coordinator → Remote state detection: remote snapshots
- Change detection → Reconciliation: normalized operations
- Remote state detection → Reconciliation: update tree
- Reconciliation → Operation execution: conflicts resolved; operations generated
- Operation execution → Local SQLite state: persists sync nodes
- Operation execution → Infomaniak APIs: downloads and uploads
- Remote state detection → Infomaniak APIs: long-poll listing
- Sync server → Observability: logs and reports
