# azeir/proton-drive-linux architecture

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

- Interactive diagram: https://gitdiagram.com/azeir/proton-drive-linux
- Repository: https://github.com/azeir/proton-drive-linux

## Overview

1. **Repository shape**
   - This is a monorepo for an offline-first Proton Drive Linux sync client.
   - The main product is a background sync daemon plus a local dashboard UI.
   - Around that core are shared SDKs, CLI tooling, service wrappers, and language bindings.

2. **Runtime/deployment boundary**
   - The executable/runtime layer is controlled by `drive.sh`, `start-sync.sh`, service templates, and systemd unit files such as `proton-sync.service`.
   - There is also a tray/helper surface (`proton-drive-tray.py`, `.desktop`) for desktop integration.
   - The daemon is intended to run as a user service and expose status/UI locally rather than as a remote web app.

3. **Sync daemon responsibilities**
   - The daemon performs the actual two-way sync between a local directory and Proton Drive cloud state.
   - Readme highlights two live inputs: remote events from Proton Drive and local filesystem changes via a watcher.
   - It supports full-sync mode as the default; the FUSE/file-on-demand path exists but is explicitly marked broken.

4. **Local state and loop prevention**
   - A local SQLite database is a core architectural boundary.
   - It tracks revision IDs, file sizes, mtimes, and related sync metadata to prevent infinite sync loops and to resolve conflicts safely.
   - Conflict handling is copy-based, producing conflict filenames instead of overwriting user edits.

5. **Authentication and secret storage**
   - Authentication is browser-assisted (`drive.sh login`) and session keys are stored in the OS keyring/secret store.
   - The shared SDKs include caches for session/account secrets and encrypted local caches, so credentials and sync state are kept separate from the remote APIs.

6. **Local dashboard / desktop shell**
   - The UI is a local dashboard served on `localhost:8085`, used to inspect status, quota, logs, pause/resume, and trigger syncs.
   - `src/` and `src-tauri/` indicate a web UI with a Rust/Tauri shell available for desktop packaging or embedding.
   - This UI is a control/observability plane; it should be diagrammed as distinct from the sync engine.

7. **JavaScript SDK core**
   - `sdk/js/sdk` is the main high-level JS library that models Proton Drive concepts and operations.
   - It is split into clear internal subsystems: auth, nodes, files, folders, volumes, shares, photos, events, upload/download, crypto, caching, telemetry, and API service layers.
   - The SDK abstracts cloud communication and local crypto/serialization so higher layers do not talk to raw endpoints directly.

8. **JS CLI as orchestration layer**
   - `sdk/js/cli` provides a command-line interface for auth, file-system operations, sharing, sync, FUSE behavior, credentials, telemetry, and event handling.
   - It also owns several local operational subsystems: SQLite-backed sync state, encrypted credential storage, transfer queues, progress reporting, conflict resolution, and local event persistence.
   - For the Linux client, this CLI layer is likely the main operator-facing control surface around the daemon and sync features.

9. **Transfer pipeline**
   - Upload and download paths are explicit pipelines, not single API calls.
   - Files are chunked, hashed, verified, encrypted/decrypted, and then sent through Proton API clients.
   - Thumbnail handling, block verification, and integrity exceptions are first-class parts of the transfer path.

10. **Cloud API surface**
   - The SDKs separate Proton’s account/auth APIs from Drive/Photos APIs.
   - Drive-side domains include files, folders, links/sharing, shares, volumes, storage, trash, events, and block verification.
   - This separation is important for the diagram: account/session management is upstream of drive object synchronization.

11. **Eventing and telemetry**
   - Remote events drive incremental sync and local event managers propagate changes through the system.
   - Telemetry is built into both SDK and CLI layers for upload/download errors, verification failures, retries, and user-visible health signals.
   - The UI and CLI consume this data for status, diagnostics, and dashboards.

12. **Other language SDKs**
   - `sdk/cs`, `sdk/kt`, and `sdk/swift` are parallel SDK implementations/wrappers for Proton Drive/Proton core functionality.
   - They include interop layers (`CExports`, JNI, Swift plumbing) and share the same conceptual boundary: API client + crypto + file transfer + telemetry.
   - These are important as cross-platform bindings, but they are separate from the Linux sync daemon’s primary runtime path.

13. **Build and packaging**
   - The repo uses Bun/Node for the JS pieces, Gradle for Kotlin, .NET for C#, Swift Package Manager for Swift, and Cargo/Tauri for the local desktop shell.
   - GitHub Actions CI is present for validation.
   - For architecture diagrams, treat these as build/distribution layers rather than runtime dependencies of the sync engine.

Main entry points: [`sdk/js/sdk/src/index.ts`](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/index.ts) (JS SDK core), [`sdk/js/cli/src/cli/index.ts`](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/cli/index.ts) (JS CLI), [`sdk/js/cli/src/sync/engine.ts`](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/sync/engine.ts) (sync engine), [`.github/workflows/ci.yml`](https://github.com/azeir/proton-drive-linux/blob/main/.github/workflows/ci.yml) (CI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_drive_sh["drive.sh<br/>launcher<br/>[drive.sh]"]
  node_start_sync_sh["start-sync.sh<br/>service start<br/>[start-sync.sh]"]
  node_proton_sync_service["sync service<br/>systemd unit"]
  node_proton_drive_tray["tray helper<br/>desktop helper"]
end

subgraph group_linuxsync["Sync client"]
  node_src_ui["dashboard UI<br/>local web ui<br/>[index.html]"]
  node_src_tauri["Tauri shell<br/>desktop shell<br/>[main.rs]"]
  node_proton_sync["sync daemon"]
  node_sync_engine["sync engine<br/>sync core<br/>[engine.ts]"]
  node_sync_db[("sync DB<br/>sqlite state<br/>[db.ts]")]
  node_event_manager(("event flow<br/>eventing<br/>[manager.ts]"))
  node_transfer_queue["transfer queue<br/>transfer orchestration<br/>[transferQueue.ts]"]
end

subgraph group_jssdk["JS SDK"]
  node_js_sdk_core["JS SDK core<br/>cloud sdk<br/>[index.ts]"]
  node_js_api_service["API service<br/>api layer<br/>[apiService.ts]"]
  node_js_transfer["Upload/Download<br/>pipeline<br/>[manager.ts]"]
  node_js_events(("Events<br/>event manager<br/>[eventManager.ts]"))
  node_js_cache_crypto["Cache/Crypto<br/>state+crypto<br/>[cryptoService.ts]"]
  node_js_cli["JS CLI<br/>operator cli<br/>[index.ts]"]
end

subgraph group_native["Native SDKs"]
  node_cs_sdk["C# SDK<br/>bindings sdk"]
  node_kt_sdk["Kotlin SDK<br/>bindings sdk"]
  node_swift_sdk["Swift SDK<br/>bindings sdk"]
end

subgraph group_build["Build"]
  node_ci["CI<br/>github actions<br/>[ci.yml]"]
end

node_drive_sh -->|"starts"| node_start_sync_sh
node_start_sync_sh -->|"installs"| node_proton_sync_service
node_proton_sync_service -->|"runs"| node_proton_sync
node_proton_drive_tray -->|"opens"| node_src_ui
node_proton_sync -->|"uses"| node_sync_engine
node_sync_engine -->|"persists"| node_sync_db
node_sync_engine -->|"consumes"| node_event_manager
node_sync_engine -->|"schedules"| node_transfer_queue
node_transfer_queue -->|"tracks"| node_sync_db
node_js_cli -->|"orchestrates"| node_js_sdk_core
node_js_sdk_core -->|"calls"| node_js_api_service
node_js_sdk_core -->|"moves data"| node_js_transfer
node_js_sdk_core -->|"subscribes"| node_js_events
node_js_sdk_core -->|"secures"| node_js_cache_crypto
node_js_cli -->|"controls"| node_sync_engine
node_js_cli -->|"uses"| node_sync_db
node_js_cli -->|"persists"| node_event_manager
node_js_cli -->|"reports"| node_transfer_queue
node_cs_sdk -.->|"mirrors"| node_js_api_service
node_kt_sdk -.->|"mirrors"| node_js_api_service
node_swift_sdk -.->|"mirrors"| node_js_api_service
node_ci -.->|"validates"| node_js_sdk_core
node_ci -.->|"validates"| node_cs_sdk
node_ci -.->|"validates"| node_kt_sdk
node_ci -.->|"validates"| node_swift_sdk

click node_drive_sh "https://github.com/azeir/proton-drive-linux/blob/main/drive.sh"
click node_start_sync_sh "https://github.com/azeir/proton-drive-linux/blob/main/start-sync.sh"
click node_proton_sync_service "https://github.com/azeir/proton-drive-linux/blob/main/proton-sync.service"
click node_proton_drive_tray "https://github.com/azeir/proton-drive-linux/blob/main/proton-drive-tray.py"
click node_src_ui "https://github.com/azeir/proton-drive-linux/blob/main/src/index.html"
click node_src_tauri "https://github.com/azeir/proton-drive-linux/blob/main/src-tauri/src/main.rs"
click node_proton_sync "https://github.com/azeir/proton-drive-linux/tree/main/proton-sync"
click node_sync_engine "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/sync/engine.ts"
click node_sync_db "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/sync/db.ts"
click node_event_manager "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/events/manager.ts"
click node_transfer_queue "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/commands/fileSystem/transferQueue.ts"
click node_js_sdk_core "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/index.ts"
click node_js_api_service "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/apiService/apiService.ts"
click node_js_transfer "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/upload/manager.ts"
click node_js_events "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/events/eventManager.ts"
click node_js_cache_crypto "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/nodes/cryptoService.ts"
click node_js_cli "https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/cli/index.ts"
click node_cs_sdk "https://github.com/azeir/proton-drive-linux/blob/main/sdk/cs/sdk/src/Proton.Drive.Sdk/ProtonDriveClient.cs"
click node_kt_sdk "https://github.com/azeir/proton-drive-linux/blob/main/sdk/kt/sdk/src/main/kotlin/me/proton/drive/sdk/ProtonDriveClient.kt"
click node_swift_sdk "https://github.com/azeir/proton-drive-linux/blob/main/sdk/swift/ProtonDriveSDK/Sources/Client/ProtonDriveClient/ProtonDriveClient.swift"
click node_ci "https://github.com/azeir/proton-drive-linux/blob/main/.github/workflows/ci.yml"

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_drive_sh,node_start_sync_sh,node_proton_sync_service,node_proton_drive_tray toneBlue
class node_src_ui,node_src_tauri,node_proton_sync,node_sync_engine,node_sync_db,node_event_manager,node_transfer_queue toneAmber
class node_js_sdk_core,node_js_api_service,node_js_transfer,node_js_events,node_js_cache_crypto,node_js_cli toneMint
class node_cs_sdk,node_kt_sdk,node_swift_sdk toneRose
class node_ci toneIndigo
```

## Components

### Runtime

User-facing daemon, launcher, service wrappers, and desktop integration.

- [drive.sh](https://github.com/azeir/proton-drive-linux/blob/main/drive.sh): launcher · Browser-assisted login and top-level client entrypoint. · `drive.sh`
- [start-sync.sh](https://github.com/azeir/proton-drive-linux/blob/main/start-sync.sh): service start · Starts the sync daemon under the user-service model. · `start-sync.sh`
- [sync service](https://github.com/azeir/proton-drive-linux/blob/main/proton-sync.service): systemd unit · Systemd service template and unit wiring for the daemon. · `proton-sync.service`
- [tray helper](https://github.com/azeir/proton-drive-linux/blob/main/proton-drive-tray.py): desktop helper · Desktop integration surface for launching and exposing status. · `proton-drive-tray.py`

### Sync client

Offline-first sync engine and local observability surface.

- [dashboard UI](https://github.com/azeir/proton-drive-linux/blob/main/src/index.html): local web ui · Local localhost dashboard for status, quota, logs, and controls. · `src/index.html`
- [Tauri shell](https://github.com/azeir/proton-drive-linux/blob/main/src-tauri/src/main.rs): desktop shell · Rust/Tauri packaging layer for embedding the local dashboard. · `src-tauri/src/main.rs`
- [sync daemon](https://github.com/azeir/proton-drive-linux/tree/main/proton-sync): daemon · Main offline-first two-way sync runtime for local folders and Proton Drive. · `proton-sync`
- [sync engine](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/sync/engine.ts): sync core · Coordinates remote events, filesystem watching, conflict handling, and sync cycles. · `sdk/js/cli/src/sync/engine.ts`
- [sync DB](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/sync/db.ts): sqlite state · SQLite-backed metadata boundary for revisions, mtimes, sizes, and loop prevention. · `sdk/js/cli/src/sync/db.ts`
- [event flow](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/events/manager.ts): eventing · Remote and local event propagation used to drive incremental sync and diagnostics. · `sdk/js/cli/src/events/manager.ts`
- [transfer queue](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/commands/fileSystem/transferQueue.ts): transfer orchestration · Queues uploads and downloads, tracks progress, and resolves conflicts. · `sdk/js/cli/src/commands/fileSystem/transferQueue.ts`

### JS SDK

Main JavaScript library and its CLI orchestration layer.

- [JS SDK core](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/index.ts): cloud sdk · High-level Proton Drive library that abstracts auth, objects, crypto, and transfers. · `sdk/js/sdk/src/index.ts`
- [API service](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/apiService/apiService.ts): api layer · Typed account/drive service layer over Proton endpoints and response mapping. · `sdk/js/sdk/src/internal/apiService/apiService.ts`
- [Upload/Download](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/upload/manager.ts): pipeline · Chunking, hashing, verification, encryption, retries, and thumbnail handling. · `sdk/js/sdk/src/internal/upload/manager.ts`
- [Events](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/events/eventManager.ts): event manager · Remote volume event polling and local event orchestration. · `sdk/js/sdk/src/internal/events/eventManager.ts`
- [Cache/Crypto](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/sdk/src/internal/nodes/cryptoService.ts): state+crypto · Encrypted caches, session secrets, and node/share crypto helpers. · `sdk/js/sdk/src/internal/nodes/cryptoService.ts`
- [JS CLI](https://github.com/azeir/proton-drive-linux/blob/main/sdk/js/cli/src/cli/index.ts): operator cli · Command-line control plane for auth, filesystem ops, sync, FUSE, telemetry, and events. · `sdk/js/cli/src/cli/index.ts`

### Native SDKs

Cross-platform bindings and alternate language implementations.

- [C# SDK](https://github.com/azeir/proton-drive-linux/blob/main/sdk/cs/sdk/src/Proton.Drive.Sdk/ProtonDriveClient.cs): bindings sdk · .NET Drive SDK with C exports and interop wrappers. · `sdk/cs/sdk/src/Proton.Drive.Sdk/ProtonDriveClient.cs`
- [Kotlin SDK](https://github.com/azeir/proton-drive-linux/blob/main/sdk/kt/sdk/src/main/kotlin/me/proton/drive/sdk/ProtonDriveClient.kt): bindings sdk · Android/JNI bindings around Proton Drive and Proton core clients. · `sdk/kt/sdk/src/main/kotlin/me/proton/drive/sdk/ProtonDriveClient.kt`
- [Swift SDK](https://github.com/azeir/proton-drive-linux/blob/main/sdk/swift/ProtonDriveSDK/Sources/Client/ProtonDriveClient/ProtonDriveClient.swift): bindings sdk · Swift package with client, file operations, and interop plumbing. · `sdk/swift/ProtonDriveSDK/Sources/Client/ProtonDriveClient/ProtonDriveClient.swift`

### Build

Packaging and CI support.

- [CI](https://github.com/azeir/proton-drive-linux/blob/main/.github/workflows/ci.yml): github actions · Repository validation and build automation. · `.github/workflows/ci.yml`

## Connections

- drive.sh → start-sync.sh: starts · Launcher delegates daemon startup and login flow.
- start-sync.sh → sync service: installs · Service wrapper targets the systemd unit.
- sync service → sync daemon: runs · Systemd user service executes the daemon runtime.
- tray helper → dashboard UI: opens · Tray/helper surfaces the local dashboard.
- sync daemon → sync engine: uses · Daemon delegates sync behavior to the sync engine.
- sync engine → sync DB: persists · Engine reads and writes loop-prevention state and revision metadata.
- sync engine → event flow: consumes · Sync cycles are driven by remote and local events.
- sync engine → transfer queue: schedules · Engine pushes file transfers and conflict-handled operations into queues.
- transfer queue → sync DB: tracks · Transfer execution updates sync metadata and progress state.
- JS CLI → JS SDK core: orchestrates · CLI commands are built on top of the main SDK.
- JS SDK core → API service: calls · SDK operations route through the typed API layer.
- JS SDK core → Upload/Download: moves data · Transfers are handled by explicit upload/download pipelines.
- JS SDK core → Events: subscribes · Incremental sync and notifications are event-driven.
- JS SDK core → Cache/Crypto: secures · Caches, secrets, and cryptography bound local and remote state.
- JS CLI → sync engine: controls · CLI is the operator-facing plane around daemon sync features.
- JS CLI → sync DB: uses · CLI owns SQLite-backed sync state and local persistence.
- JS CLI → event flow: persists · CLI provides local event persistence and managers.
- JS CLI → transfer queue: reports · CLI exposes progress, retries, and conflict handling to operators.
- C# SDK → API service: mirrors · Parallel SDK implementation over the same account/drive concepts.
- Kotlin SDK → API service: mirrors · Kotlin binding layer follows the same conceptual API boundary.
- Swift SDK → API service: mirrors · Swift SDK matches the same client and file-operation boundary.
- CI → JS SDK core: validates · CI covers the monorepo's build and test surfaces.
- CI → C# SDK: validates · CI validates cross-platform SDK builds.
- CI → Kotlin SDK: validates · CI validates Gradle/JNI packaging.
- CI → Swift SDK: validates · CI validates Swift package builds.