TinySync Architecture
Reference

01 / Product Shape

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.

02 / System Context — C4 Level 1

At the highest level, TinySync sits between users on multiple devices and the infrastructure that stores their files.

03 / Container Architecture — C4 Level 2

Each device runs several co-operating processes. The engine is separated from the OS integration layer, and a background daemon owns all mutable engine state.

04 / Sync Engine Components — C4 Level 3

The daemon contains tinysync-engine — the heart of the system. It is isolated behind two traits: one facing the cloud, one facing the OS.

The Two Trait Boundaries

trait CloudClient {
  get_snapshot(vault_id) → Snapshot
  get_log(vault_id, after: Seq)
    → LogPage
  upload_blob(vault_id, hash, bytes)
  download_blob(vault_id, hash)→Bytes
  submit_mutation(vault_id, req)
    → MutationResponse
}

trait PresentationAdapter {
  hydration_strategy()→Eager|Lazy
  apply_create(item, content)
  apply_update(item, content)
  apply_delete(item)
  apply_move_rename(from, to)
  enumerate_local()→Vec<LocalEntry>
  read_local_content(path, hash)→Bytes
  preserve_conflict_copy(path,
    op_id, device_id)→Option<VPath>
}

05 / Crate Map

06 / Core Data Model — The Item Tree

Items

The fundamental entity is an item — a file or a folder. Items form a tree rooted at a synthetic root folder. All items have a parent item ID, except the vault root.

struct ItemView {
    item_id:        Uuid,          // stable — never changes across rename/move
    parent_item_id: Option<Uuid>, // None only for vault root
    name:           String,        // filename only, no path separators
    path:           VPath,         // derived from ancestry — not stored as primary key
    kind:           ItemKind,      // File | Folder
    version:        u64,           // incremented on each accepted mutation
    metadata:       ItemMetadata,
}

struct ItemMetadata {
    content_hash: Option<Hash>, // SHA-256 of content, files only
    size:         u64,
    mtime:        Option<DisplayTime>, // display only — NOT ordering truth
    deleted:      bool,
}

Content Addressing

File content is stored separately from metadata. The server's blobs table is keyed by SHA-256(content). A file mutation first PUTs the blob (idempotent — the hash is the key), then submits a metadata mutation referencing that hash. Two files with identical bytes reference the same blob automatically.

Folder Subtree Semantics

• Move/rename folder — one mutation, one change log event (MovedRenamed). Descendants' IDs don't change. Client rederives paths from the updated ancestry. A folder with 1,000 files is one operation, not 1,000.
• Delete folder — one server transaction tombstones the folder and all descendants. The change log emits one DeleteSubtree event rather than one event per descendant.

Filename Rules (enforced at server boundary)

07 / Local Item State Machine

Every item in the local engine has a LocalKind value tracking its state relative to the server and local filesystem. Persisted in SQLite — survives crashes and restarts.

Move and rename operations do not change LocalKind. They update parent_item_id and name, and the engine rederives all affected path caches.

08 / Server-Side Schema

The server stores all authoritative state in PostgreSQL. The change log is the ordering backbone of the entire system.

-- Vault: root of a synced file tree
CREATE TABLE vaults (
    vault_id     UUID PRIMARY KEY,
    root_item_id UUID NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL
);

-- Item tree: every file and folder
CREATE TABLE items (
    item_id          UUID PRIMARY KEY,
    vault_id         UUID NOT NULL REFERENCES vaults,
    parent_item_id   UUID,
    name             TEXT NOT NULL,
    normalized_name  TEXT NOT NULL,   -- casefold for collision checks
    kind             TEXT NOT NULL,   -- File | Folder
    item_version     BIGINT NOT NULL, -- precondition for mutations
    content_hash     BYTEA,          -- SHA-256 of content, files only
    size             BIGINT,
    deleted_at       TIMESTAMPTZ,
    created_at       TIMESTAMPTZ NOT NULL,
    updated_at       TIMESTAMPTZ NOT NULL
);

-- Unique sibling names among live items
CREATE UNIQUE INDEX items_live_sibling_name
    ON items(vault_id, parent_item_id, normalized_name)
    WHERE deleted_at IS NULL;

-- Content-addressed blob store
CREATE TABLE blobs (
    content_hash BYTEA PRIMARY KEY,   -- SHA-256 is the key
    size         BIGINT NOT NULL,
    storage_key  TEXT NOT NULL,
    created_at   TIMESTAMPTZ NOT NULL
);

-- Authoritative ordered change log
CREATE TABLE change_log (
    vault_id      UUID NOT NULL,
    seq           BIGINT NOT NULL,    -- monotonically increasing per vault
    op_id         UUID NOT NULL,
    device_id     UUID NOT NULL,
    item_id       UUID NOT NULL,
    event_kind    TEXT NOT NULL,      -- Created|Updated|Deleted|DeleteSubtree|MovedRenamed
    event_payload JSONB NOT NULL,
    committed_at  TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (vault_id, seq)
);

-- Idempotency: replay-safe operation results
CREATE TABLE idempotency_keys (
    vault_id         UUID NOT NULL,
    device_id        UUID NOT NULL,
    op_id            UUID NOT NULL,
    request_hash     BYTEA NOT NULL,
    response_payload JSONB NOT NULL,
    created_at       TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (vault_id, device_id, op_id)
);

-- Identity & access (migration 0004): a device is a physical
-- machine — one row, one credential, ever.
CREATE TABLE devices (
    device_id       UUID PRIMARY KEY,
    display_name    TEXT NOT NULL,
    credential_hash BYTEA NOT NULL CHECK (length(credential_hash) = 32),
    registered_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_seen_at    TIMESTAMPTZ,
    revoked_at      TIMESTAMPTZ
);

-- Opaque to TinySync; meaning lives in the Platform Service.
CREATE TABLE groups (
    group_id     UUID PRIMARY KEY,
    display_name TEXT NOT NULL DEFAULT '',
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE group_devices (
    group_id  UUID NOT NULL REFERENCES groups ON DELETE CASCADE,
    device_id UUID NOT NULL REFERENCES devices ON DELETE CASCADE,
    added_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (group_id, device_id)
);

CREATE TABLE group_vaults (
    group_id UUID NOT NULL REFERENCES groups ON DELETE CASCADE,
    vault_id UUID NOT NULL REFERENCES vaults ON DELETE CASCADE,
    added_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    PRIMARY KEY (group_id, vault_id)
);

Retention

The server exposes min_retained_seq alongside latest_seq. A client reconnecting after last_seq_processed < min_retained_seq must run a full snapshot resync rather than incremental log replay.

09 / Sync Protocol — Bootstrap

When a device first joins a vault, or when local state is too stale for incremental replay, it runs bootstrap: snapshot + log replay.

10 / Normal Sync Cycle

After bootstrap, the engine runs sync_once on every trigger — WebSocket wake, file watcher notification, or timer. Three phases, always in this order.

11 / The Mutation Contract

Every change a client proposes is a typed mutation request that the server may accept or reject.

Mutation Types

enum MutationRequest {
    CreateFile {
        op_id, parent_item_id, item_id, name,
        content_hash, size          // blob must already be uploaded
    },
    CreateFolder { op_id, parent_item_id, item_id, name },
    ModifyFile {
        op_id, item_id,
        base_item_version,          // optimistic concurrency precondition
        content_hash, size
    },
    Delete  { op_id, item_id, base_item_version },
    MoveRename {
        op_id, item_id, base_item_version,
        to_parent_item_id, new_name  // atomic — never decomposed into delete + create
    },
}

Server Acceptance Conditions

• Device credential is valid and not revoked.
• op_id is new, or exactly repeats a prior operation (idempotent replay).
• Name passes cross-platform validation.
• No live sibling with the same normalized name at the target parent.
• base_item_version matches the current server version for existing-item mutations.
• Parent folder exists and is not deleted.
• File content blob is already present in the blob store for file mutations.

Idempotency

Every mutation carries an op_id (UUID generated by the client, persisted to SQLite before sending). If the network fails after the server commits but before the client receives the response, the client retries with the identical op_id. The server returns the original result from the idempotency_keys table.

// Guarantees exactly-once effect despite retries
op_id = OpId::new()
persist_pending_op(op_id, request)   // written to SQLite FIRST
upload_blob_if_needed(content)
response = submit_mutation(request)  // safe to retry with same op_id
if response.accepted:
    complete_pending_op(op_id)

12 / Conflict Resolution

Not "last writer wins"

TinySync's model is more precise: first writer whose base version is still current wins. base_item_version on every existing-item mutation is an optimistic concurrency precondition. If Device A and B both start from version 5, and A's mutation arrives first (incrementing to version 6), B's mutation with base_item_version=5 is rejected — not silently overwriting A's confirmed write.

Conflict Policy (v1)

The policy is pluggable — resolve_conflict returns a list of actions and can be swapped without touching the engine:

1. Accept the server's current version at the original item path.
2. Rename local losing content to <name> (TinySync conflict <device> op <op_id>).<ext>.
3. Reclassify the conflict file as a fresh local create and upload it.
4. Both versions survive. All devices converge. No data is lost.

13 / Engine Lifecycle States

The engine has five states, persisted in the engine_state SQLite table. Transitions are explicit and logged.

14 / OS Adapter Layer

The OS native provider layer is where files appear in Finder and Explorer, and where lazy hydration happens. It is the most novel architectural feature relative to a traditional sync system.

Adapter Methods

15 / Auth & Device Model

TinySync has no traditional user account. Authentication is device-scoped — one identity per physical machine — and authorization is group membership, resolved at request time.

API surface

16 / Critical Design Invariants

These are load-bearing. Violating any one breaks correctness, safety, or recoverability.

17 / Key Design Decisions

The decisions below shaped the architecture in ways that are not obvious from the structure alone. Each entry covers what was rejected and why — so future contributors don't re-litigate settled questions without new information.

Language: Rust, not Go

Topology: Cloud-authoritative, not P2P

Build order: Engine-first, OS adapters later

Process architecture: Thin extension + daemon, not engine-in-extension

Desktop app role: Tauri as control plane only

IPC protocol: Bounded JSON over local sockets, not gRPC

Write path: Native-provider writes bypass PresentationAdapter

18 / v1 Scope

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

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 BlobStore trait. 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 CLI and daemon store the device token as plaintext in identity.json under the state root with owner-only 0600 permissions. The packaged desktop app should move its copy into 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.

19 / Local Mutations & Device Fanout

This section traces the complete lifecycle of a file change — from the moment a user saves a file on Device A to the moment it appears on Device B and C. There are two directions: local → cloud (mutations) and cloud → local (log replay). They are deliberately decoupled.

The two directions

Local mutation path — step by step

Server commit & fanout

When the server accepts a mutation it does three things in one transaction: updates the item record (bumping item_version), appends to change_log (assigning seq), and records the idempotency result. After the transaction commits, it triggers fanout.

Full end-to-end: A modifies, B and C receive

Concurrent writes from multiple devices

Multiple devices can submit mutations for the same item concurrently. The server is the arbiter. The first mutation whose base_item_version matches the current server state is accepted and assigned a seq. All others are rejected with StaleBaseItemVersion. The losing device's local content is preserved as a conflict copy (see §12).

This means the server never merges — it serialises. The seq is the total order across all vaults. Within a vault, item_version is the per-item optimistic lock.

Offline durability

When a device is offline, local changes continue to queue in pending_ops (SQLite). The device's local filesystem reflects the user's changes immediately. On reconnect:

1. Check last_seq_processed against server's min_retained_seq.
2. If within the retention window → incremental GET /log?after=N replay.
3. If the cursor has fallen behind min_retained_seq (device was offline > 90 days) → full snapshot resync.
4. After pulling remote changes, submit all queued pending_ops in creation order.

20 / Device Authentication & Access

TinySync uses a custom bearer token scheme — not JWT. The design is deliberately minimal: stateless parsing, one database lookup per request, and immediate per-device revocation without token expiry windows.

Why not JWT

JWT is self-contained — the server can validate a token without a database round-trip. This is its main advantage. But TinySync's threat model requires immediate per-device revocation: if a device is lost or compromised, its credential must be dead the moment an admin revokes it. JWT cannot provide this without a revocation list — which is a database lookup anyway. Since TinySync already hits Postgres on every sync API call, the lookup costs nothing extra. Self-contained claims provide no benefit and add unnecessary surface area.

Token anatomy

All tokens follow the same structure: a typed prefix, a stable identifier, and a high-entropy secret — joined by underscores.

Device token:   tsdev_{device_id}_{secret}
Public link:    {secret}   (bare base64url, no prefix)
Admin token:    static value from TINYSYNC_ADMIN_TOKEN (env)

The secret in every case is 32 random bytes, base64url-encoded without padding — giving a 43-character string. The server generates this with thread_rng().fill_bytes() (device) or OsRng.fill_bytes() (public links, where the stronger CSPRNG is preferred since the token is the only auth factor).

The server never stores the raw secret. It stores:

SHA-256("tinysync:v1:{kind}:" || secret_bytes)

The domain prefix (tinysync:v1:device:, tinysync:v1:public_link:, etc.) ensures the same raw bytes produce a different hash for different token kinds — preventing cross-kind token confusion even if secrets were ever reused.

Token types & properties

Request authentication flow

Device lifecycle

Registration flow — adding a new device

Registration replaces the old join-token exchange. It issues an identity, not access — a freshly registered device reaches nothing until an admin grants it group membership.

1. The device calls POST /v1/devices { display_name }. Open by default; with TINYSYNC_OPEN_DEVICE_REGISTRATION=false the admin token is required (the Platform-Service-mediated mode).
2. The server creates the device record, stores the credential hash, and returns the raw device token once.
3. An admin (or the Platform Service) grants access: PUT /v1/groups/{gid}/devices/{did} and PUT /v1/groups/{gid}/vaults/{vid}.
4. The raw device credential is stored by the client in identity.json under the state root with 0600 permissions. It is never sent to the server again as a raw value — only used to construct request headers.

Revocation

Revoking a device sets revoked_at on its record — the row and its credential hash are retained so change-log attribution survives. Every subsequent request from that device returns 403 "device is revoked". Revocation is global: the one credential dies across every vault at once. No other device is affected. Removing a device from a single vault is a group-membership edit (DELETE /v1/groups/{gid}/devices/{did}), not a revocation.

If a device creates public share links, those can be bulk-revoked at the same time: POST /v1/devices/{id}/revoke accepts a flag revoke_public_links_created_by_device: true. This is the intended response to a compromised device.

Security properties

21 / Drive as a Service — Platform Integration

TinySync is a sync primitive — it understands vaults and devices. It does not understand users, teams, projects, or products. This is intentional. The goal of "Drive as a Service" is to define the thinnest possible interface that lets ecosystem products leverage TinySync without forcing TinySync to absorb identity concerns it should not own.

The three-layer model

Ownership boundary

Data model — which tables live where

Access model — three levels of fan-out

Access can be granted at any of three levels. The Platform Service is responsible for expanding higher-level grants downward to devices.

TinySync sees only the bottom two rows — devices and device tokens. The group and user structure above that is entirely the Platform Service's concern.

Token orchestration — provisioning device × vault access

The fundamental operation: given a (user, vault) grant, ensure every device that user owns has a valid device token for that vault. This is called token provisioning.

Vault creation — product-driven

Ecosystem products create vaults via the Platform Service, not directly against TinySync. The Platform Service calls TinySync's admin API and records metadata on both sides.

Container tags and policy layer

A container is a product's namespace within Drive. Every vault created by a product carries that product's container tag (e.g. tasket:project, notes:personal). The tag is stored on the vault in TinySync and is visible in the change log, enabling per-product behaviour without TinySync understanding product semantics.

Container-level policies are owned by the Platform Service. They are delivered to devices as part of the vault bootstrap configuration — alongside the device token, not inside TinySync's sync protocol.

Web view layer

The Platform Service hosts web experiences per product. A web session authenticates against the Platform (not TinySync directly) and receives a short-lived session token scoped to the user's accessible vaults. The web app calls the Platform's read-through API, which proxies to TinySync for file tree and history data.

Web sessions use session tokens (tssess_...) — not device tokens. A browser is not a sync device; it gets read access to the vault's current snapshot and history, not the sync protocol.

Access revocation and group membership changes

When a user's access changes (leaves a group, vault access revoked), the Platform Service must revoke their devices' TinySync credentials for the affected vaults. This is a cascade the Platform owns entirely — TinySync just executes the revocations.

Open questions

• Platform admin credential model. The Platform Service needs an admin-level credential to call TinySync (create vaults, generate join tokens, revoke devices). Should this be a static admin token per environment, or a short-lived service token per operation? Static is simpler; short-lived is safer.
• Eager vs lazy provisioning. Lazy handles offline devices but adds latency (device must check in before it can sync a newly granted vault). Eager is instant but burns join tokens. A hybrid — eager for online devices, lazy fallback — may be the right default.
• Group membership change propagation time. When a user is removed from a group, how quickly must their TinySync access be revoked? Real-time revocation requires the Platform to call TinySync synchronously. Eventual (next sync cycle) may be acceptable depending on the product's threat model.
• Multi-vault device bootstrap. A device may have access to many vaults (personal, multiple team projects). Should the device maintain one SQLite engine per vault (current model) or a shared engine with vault partitioning? Current model works but may need UX to manage which vaults are synced on which device.
• Policy versioning. Container policies will evolve. When a policy changes (e.g. syncignore rules tightened), already-synced files that violate the new policy need handling. Define a policy version in bootstrap config; client re-evaluates on policy version bump.
• Web blob access. Should the web app download blobs directly from TinySync's blob endpoint (efficient, requires a valid token) or via a Platform-proxied URL (allows Platform to enforce per-file permissions)? Direct is simpler; proxied gives finer-grained access control.
• Shared devices. If two users share a physical device (family Mac), each user needs separate device registrations per vault. The client must support multiple vault credentials on one device and associate each with the appropriate user session.

What TinySync needs to add to support this

Almost nothing. The design intentionally keeps TinySync unchanged. The only additions that would help:

• Batch join token creation. Provisioning tokens one at a time when a large group is granted access is slow. A single POST /vaults/{id}/join-tokens/batch endpoint with a count parameter would help the Platform Service.
• Batch device revocation. Similarly, revoking all devices for a user across all vaults in one call is cleaner than N individual revocations.
• Container tag filtering on vault listing. GET /vaults?container_tag=tasket:project — useful for the Platform to enumerate vaults it owns without a full scan.
• Webhook on device sync activity. Optional. Lets the Platform Service track last-seen-at per device without polling.

The sync protocol, change log, blob store, and conflict model require zero changes. Drive-as-a-service is a thin API layer above an unchanged sync engine.