Technical Specification
Specification Contents
Section titled “Specification Contents”This specification is split across the following pages:
- Overview, Architecture & Protocol Stack — this page
- Security Model — key hierarchy, threat model, trust assumptions
- Wire Protocol — message specification and envelope format
- Client Library — public API, configuration, events, encryption flow
- Relay Server — responsibilities, storage schema, behavior, rate limits
- Pairing & Devices — pairing flow, device revocation
- Integration — framework integration (Tauri) and mobile lifecycle
- Configuration — tier config, error handling, config reference, best practices
- Content Transfer — push notifications and large content transfer protocol
- Multi-Language Bindings — sync-bridge, napi-rs, PyO3, Tauri plugin
- Vault Mode — cloud backup, object storage, restore flow, crate dependencies
1. Overview
Section titled “1. Overview”1.1 Purpose
Section titled “1.1 Purpose”0k-Sync provides secure, zero-knowledge synchronization between multiple instances of any local-first application across devices (desktop, mobile, web).
1.2 Design Principles
Section titled “1.2 Design Principles”| Principle | Meaning |
|---|---|
| Zero Knowledge | Relay cannot decrypt user data |
| Local-First | Apps work offline; sync is opportunistic |
| Pass-Through Only | Relay routes messages, does not store data long-term |
| Client Constant | Same client library for all relay tiers |
| Open Standards | 100% open source dependencies |
1.3 Non-Goals
Section titled “1.3 Non-Goals”- Real-time collaborative editing (CRDTs are app responsibility)
- File sync (use Syncthing; this is for app state)
- User accounts (zero-knowledge, QR pairing only)
- Background sync on mobile (OS limitations)
- Data storage (relay is ephemeral)
2. Architecture
Section titled “2. Architecture”2.1 Component Overview
Section titled “2.1 Component Overview”
2.2 Component Responsibilities
Section titled “2.2 Component Responsibilities”| Component | Responsibility |
|---|---|
| Application | Business logic, CRDT merge, conflict resolution, UI |
| Framework Integration | Platform bindings (optional), state management, events |
| sync-client | E2E encryption, connection, cursor tracking, pairing |
| sync-types | Wire format, message definitions, shared types |
| sync-core | Pure logic (state machine, buffer), no I/O |
| sync-relay | Connection management, message routing, temp buffer |
2.3 Data Flow
Section titled “2.3 Data Flow”
3. Protocol Stack
Section titled “3. Protocol Stack”3.1 Layer Diagram
Section titled “3.1 Layer Diagram”
Amendment (2026-02-02): Layer structure updated per iroh-deep-dive-report.md recommendations. Added Layer 3 (Content Transfer) for large file handling via iroh-blobs. Layer 0 now explicitly includes mDNS local discovery and ALPN routing.
3.2 Serialization
Section titled “3.2 Serialization”Format: MessagePack (rmp-serde)
Rationale:
- Binary format (smaller than JSON)
- Schema-less (flexible evolution)
- Well-supported in Rust
- Cross-platform compatibility