# Architecture

`DriveEngine` owns file state, transfers, cache, staging, conflict decisions and provider calls. `DriveProvider` isolates Proton integration churn; `FakeDriveProvider` exercises the same core without credentials. Real accounts use `OfficialCliProvider`, which keeps Proton authentication and cryptography inside a CLI built from pinned official source. `ProtonSdkProvider` remains a tested direct-SDK seam for a future published authentication package; it is deliberately not selectable in `main.ts` today (no production entry point).

The daemon exposes a versioned newline-delimited RPC protocol on a user-only Unix socket. FUSE, the control helper, Nautilus and Quattro consume that protocol. A long-running `Watch` request emits node and transfer changes so UI state is event-driven.

Local layout:

| Data | Location | Evictable |
|---|---|---|
| downloaded content | `$XDG_CACHE_HOME/omarchy-drive/content` | yes, only clean and unpinned |
| metadata/state | `$XDG_STATE_HOME/omarchy-drive/state*.sqlite` (private WAL) | no |
| unsynced writes | `$XDG_STATE_HOME/omarchy-drive/staging` | never automatically |
| conflict copies | `$XDG_STATE_HOME/omarchy-drive/conflicts` | never automatically |

SQLite transactions persist metadata, node state and event cursors; legacy JSON snapshots migrate on first startup. Only changed rows are written, while root, parent/child and child-name indexes stay in memory for constant-time lookup. `remoteRevision` describes current metadata and `cacheRevision` describes the bytes actually stored locally; they are never inferred from each other. Remote changes invalidate clean cache regardless of pin state, and startup removes unverifiable legacy entries and orphaned download files. Writes first land in persistent staging, then upload after engine and provider revision checks. A detected mismatch preserves local bytes and marks a conflict. Remote deletion, cache eviction and uninstall are blocked while the only unsynchronised copy could be local.

Folder browsing uses stale-while-revalidate metadata: known children return immediately from SQLite, one deduplicated provider refresh runs in the background after a 30-second freshness window, and FUSE retains one immutable listing per open directory handle plus a five-second cross-handle cache. Fresh folder metadata is also reused when opening and recursively pinning files, avoiding a separate CLI metadata process for every node. Direct lookup does not serialize the complete directory. Interactive CLI work takes priority over queued maintenance. Direct-subfolder warming defaults to 12 for SDK/fake providers and 0 for the process-based CLI provider; it uses concurrency 2 when enabled. These defaults can be tuned with `OMARCHY_DRIVE_LISTING_TTL_MS`, `OMARCHY_DRIVE_PREFETCH_FOLDERS`, `OMARCHY_DRIVE_PREFETCH_CONCURRENCY`, `OMARCHY_DRIVE_FUSE_ATTRIBUTE_TTL`, and `OMARCHY_DRIVE_FUSE_DIRECTORY_TTL`. Transfer updates are coalesced to at most one progress event per 100 ms while terminal states remain immediate; terminal history is capped at 256 entries so long sessions cannot grow it without bound. FUSE, D-Bus, Nautilus, control and smoke tooling use the shared RPC client, whose response buffer is capped at 8 MiB. `OMARCHY_DRIVE_CLI_TIMEOUT_MS`, `OMARCHY_DRIVE_CLI_MAX_BUFFER_BYTES`, `OMARCHY_DRIVE_RPC_TIMEOUT_MS`, and the client-side `OMARCHY_DRIVE_RPC_TIMEOUT_SECONDS` bound slow operations and provider output. The QML control path applies a stricter 256 KiB per-message limit and a 16 MiB accumulated watch-process limit before writing to Quickshell. Server timeout and socket disconnect both request cancellation instead of returning while a cooperative mutation continues; Nautilus deliberately uses a fixed 250 ms client timeout to avoid blocking the file-manager UI.

Nautilus reads node ID and local sync status from FUSE extended attributes. This avoids one Unix-socket round trip per visible file; thumbnail suppression is limited to MIME types for which a thumbnailer is relevant and repeated work is skipped until the URI status or modification time changes.

The FUSE adapter waits up to 30 seconds (`OMARCHY_DRIVE_FUSE_STARTUP_TIMEOUT`) for the daemon socket before mounting, so systemd dependency ordering does not turn normal daemon startup into a mount restart. It also waits briefly for a just-closed file to finish uploading before rename/replace (`OMARCHY_DRIVE_FUSE_MUTATION_TIMEOUT`, 30 seconds by default), while still refusing mutation if recoverable bytes remain unsynchronised. The D-Bus bridge likewise retries quietly during initial startup and reports reconnect failures after the integration has been established or startup remains unavailable for 30 seconds.

The mount directory follows `$XDG_DATA_HOME` and is written to the private service environment during installation, so FUSE, D-Bus, Nautilus, the control helper and the GTK bookmark resolve the same location. Authentication commands first stop the mount, D-Bus bridge and daemon, then restart them in a `finally` path, preventing their shared official-CLI cache from being used concurrently with login or logout.