Skip to content

Architecture

develicit edited this page Nov 16, 2026 · 2 revisions

Architecture

clipsync-core coordinates the client. The CLI, desktop UI, and mobile bindings share its pairing and synchronization behavior, while dedicated crates handle OS access, networking, and storage.

Components

flowchart TB
  subgraph Device["Client device"]
    CLI["clipsync CLI"] --> Core["clipsync-core: App / sync engine"]
    Desktop["Desktop UI: egui / eframe"] --> Core
    Mobile["Mobile: UniFFI / ClipboardBridge"] --> Core
    Core --> Clipboard["clipsync-clipboard: OS adapters"]
    Core --> Storage["clipsync-storage: configuration / metadata / secrets"]
    Core --> Crypto["clipsync-crypto: pairing / keys / AEAD / Noise"]
    Core --> Transfer["clipsync-transfer: chunks / validation / staging"]
    Core --> Daemon["clipsync-daemon: service management / per-user IPC"]
    Core --> Transport["clipsync-transport: HTTP / WebSocket / TLS"]
  end
  Transport <-->|"HTTPS / WSS"| Relay["clipsync-relay: authentication / membership / ciphertext routing"]
  Relay <-->|"Encrypted messages"| Peer["Peer device"]
  Relay -->|"Optional metadata"| Webhook["External webhook"]
Loading

Internal arrows show the main call and usage relationships. clipsync-protocol defines shared messages and limits; Repository structure lists the direct Cargo dependencies.

Processes and lifetimes

Execution unit Responsibility Lifetime and state
clipsync command Initialization, room creation and joining, status and configuration queries, manual transfers Ordinary commands exit when complete. Room creation detaches pairing into another process by default.
clipsync daemon run Clipboard watching, network sessions, local IPC Runs as a per-user login service. The sync engine is implemented in clipsync-core.
clipsync-desktop A window for room creation, joining, and status Calls the core and queries daemon status over IPC. The window and login daemon are separate execution units.
Mobile application UniFFI calls and host clipboard integration ClipSyncClient calls the core; the native application controls its lifecycle and clipboard permissions.
clipsync-relay Pairing sessions, token validation, connections, and forwarding Runs as a server process. Rooms, membership, and queued text are in-memory state.

macOS uses a LaunchAgent, Linux uses a systemd user service and desktop autostart, and Windows uses a login Startup entry. Local IPC uses Unix sockets or Windows named pipes. Processes running with the same user's access are inside the local trust boundary.

Responsibility boundaries

A shared core reduces the need to duplicate pairing and validation rules in the UI and CLI. The clipboard adapter boundary lets OS implementations and mobile callbacks use the same engine. Sharing protocol types between clients and the relay provides one place to inspect message formats and limits.

The relay routes ciphertext and does not assemble files. It therefore does not need to decrypt content, but delivery timing, connection information, routing metadata, and server availability remain part of the trust model. In particular, pairing requires trust in the relay that generates the code; see Security and storage.

Code entry points

Clone this wiki locally