How azeir/proton-drive-linux works
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: src/index.ts JS SDK core · cli/index.ts JS CLI · engine.ts sync engine · ci.yml CI
Components 21
Runtime
User-facing daemon, launcher, service wrappers, and desktop integration.
- drive.sh · Browser-assisted login and top-level client entrypoint.
drive.sh - start-sync.sh · Starts the sync daemon under the user-service model.
start-sync.sh - sync service · Systemd service template and unit wiring for the daemon.
proton-sync.service - tray 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 · Local localhost dashboard for status, quota, logs, and controls.
src/index.html - Tauri shell · Rust/Tauri packaging layer for embedding the local dashboard.
src-tauri/src/main.rs - sync daemon · Main offline-first two-way sync runtime for local folders and Proton Drive.
proton-sync - sync engine · Coordinates remote events, filesystem watching, conflict handling, and sync cycles.
sdk/js/cli/src/sync/engine.ts - sync DB · SQLite-backed metadata boundary for revisions, mtimes, sizes, and loop prevention.
sdk/js/cli/src/sync/db.ts - event flow · Remote and local event propagation used to drive incremental sync and diagnostics.
sdk/js/cli/src/events/manager.ts - transfer queue · 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 · High-level Proton Drive library that abstracts auth, objects, crypto, and transfers.
sdk/js/sdk/src/index.ts - API service · Typed account/drive service layer over Proton endpoints and response mapping.
sdk/js/sdk/src/internal/apiService/apiService.ts - Upload/Download · Chunking, hashing, verification, encryption, retries, and thumbnail handling.
sdk/js/sdk/src/internal/upload/manager.ts - Events · Remote volume event polling and local event orchestration.
sdk/js/sdk/src/internal/events/eventManager.ts - Cache/Crypto · Encrypted caches, session secrets, and node/share crypto helpers.
sdk/js/sdk/src/internal/nodes/cryptoService.ts - JS 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 · .NET Drive SDK with C exports and interop wrappers.
sdk/cs/sdk/src/Proton.Drive.Sdk/ProtonDriveClient.cs - Kotlin 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 · Swift package with client, file operations, and interop plumbing.
sdk/swift/ProtonDriveSDK/Sources/Client/ProtonDriveClient/ProtonDriveClient.swift
Build
Packaging and CI support.
- CI · Repository validation and build automation.
.github/workflows/ci.yml
Connections 25
- 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.