Repository navigation
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.
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"]
Internal arrows show the main call and usage relationships. clipsync-protocol defines shared messages and limits; Repository structure lists the direct Cargo dependencies.
| 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.
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.
- App facade: public operations used by commands and UIs.
- Sync engine: daemon, send/receive sessions, and applying received items.
- Pairing coordinator: creator and joiner state transitions and persistence.
- Relay router and WebSocket handling: HTTP and WS boundaries.
- Repository architecture document: the design overview maintained with the source.
Baseline: source 76c63f9 · 2026-11-16 · Wiki home · Source repository. The wiki is a separate Git repository and is not synchronized with product sources automatically.