What TinySync is
TinySync is a cloud-authoritative file sync engine. Think Dropbox — not a database sync library, not a collaborative editing framework, not a peer-to-peer tool.
The product contract: put a file in a cloud drive location on any device, and it appears — on demand — on every other device. The OS presents the drive as if all files exist locally, even when content hasn't been downloaded yet (placeholders). Files hydrate when opened.
Topology
The cloud server is the single source of truth. No peer-to-peer, no CRDT merge, no multi-master replication. Every write from any device must be accepted by the server before becoming canonical. Other devices learn about it by replaying the server's ordered change log.
This eliminates "where is the real version?" ambiguity and makes conflict resolution deterministic: the first write whose precondition still holds wins; all others get conflict copies.
What it is not
TinySync is not a CRDT collaborative editor. There is no operational-transform engine, no real-time co-editing, and no character-level merge. Two users editing the same file concurrently will produce a conflict copy — not a merged document. That is a deliberate choice, not an oversight: the target use case is personal cloud storage, not Google Docs.
TinySync is also not a row-level app-data sync layer. It does not understand schemas, foreign keys, or query semantics. If you need structured data synced across clients with a query interface, something like PowerSync is the right tool for that job — see the PowerSync decision record for how these two tools compare and when to reach for each.
System context
At the highest level, TinySync sits between users on multiple devices and the infrastructure that stores their files.
| System | Role |
|---|---|
| TinySync Server | Accepts mutations, maintains the authoritative change log, serves snapshots and log pages, hosts blob upload/download, pushes WebSocket wake notifications. |
| PostgreSQL | Authoritative store for vault metadata, item tree, change log (ordered by seq), device identities, groups and membership edges, idempotency keys, public link records. |
| Blob Store | Content-addressed binary store keyed by SHA-256(content). Identical files share one blob. Local filesystem in dev; object storage (R2/S3/B2) in production. |
Scope honesty: v1
TinySync v1 is deliberately narrow. The bet is that one thing done bulletproof beats ten things done okay. The items below are not forgotten — they are explicitly deferred because they would delay a correct, shippable core.
Explicitly cut for v1
| Feature | Why deferred |
|---|---|
| Shared folders / collaboration | Auth and per-folder permissions alone is months of work. Not on the critical path for a personal cloud drive. |
| Selective sync UI | Subsumed by on-demand hydration. If a file hasn't been opened, it hasn't been downloaded. The OS handles this transparently. |
| Version history / restore | Tombstone retention covers recoverability. A full version UI requires storage policy, API surface, and UI complexity not on the critical path. |
| Block-level dedup / binary diffs / content-defined chunking | Whole-file content-addressing ships first. These are post-beta optimization work — they don't change the protocol shape. |
| LAN sync / peer-assist | Optimization on top of the cloud-ordered log, not a topology change. Add it after the cloud path is proven. |
| E2E encryption | Complicates server-side dedup, conflict diagnostics, and abuse handling. Only adopt if it becomes the core product thesis. |
| Bandwidth limiters / schedules | Configuration knobs, not core correctness. Add when users ask. |
| Mobile clients | Different OS APIs (iOS Files app, Android Storage Access Framework) and different lifecycle. A separate effort. |
| Predictive prefetch | An aesthetic layer above correct lazy hydration. Build after hydration is reliable. |
| Conflict merge UI | Optimistic concurrency with conflict-copy preservation covers v1. A merge UI can layer on the same storage model later. |
| Trash / undelete | Tombstone retention (90 days) covers recoverability. A trash UI with restore requires additional storage policy and API surface. |
| Multi-user accounts on one device | Outside the vault-token model. Each vault has its own device roster; a multi-user system requires a user layer above vaults. |
Open questions — deliberately deferred
These are not decided. They are punted until they materially affect a decision that must be made now.
- Object storage provider (R2 vs B2 vs raw S3) — abstracted behind the
BlobStoretrait. Pick when production hosting matters. The choice has no protocol implications. - Tombstone retention window — likely 90 days; decide before the first migration that touches tombstones. Configuration, not architecture.
- File size cap above 50 MB — fine for v1. Revisit when video or large photos enter scope. The cap is a single constant; raising it has no structural implications.
- E2E encryption — depends on product positioning, not technical readiness. The current architecture does not preclude it, but adding it requires rethinking server-side dedup and conflict diagnostics.
- Sync semantics backlog — folder concurrency races, temp/lock file policy, debounce and write coalescing, large-file transfer strategy, cross-platform path edge cases, and provider retry deduplication are tracked separately. Known hardening work; not current blockers.
- Production credential storage — the prototype CLI stores device tokens as plaintext in
client.tomlwith best-effort0600permissions. Production clients must use the platform keychain / credential manager.
Locked — do not reopen without new information
These were debated and decided. Reopening requires a genuinely new constraint, not just a new mood.