zpan/docs/roadmap/v2.10.md

v2.10 — Desktop Sync Foundation

Prepare ZPan for real desktop sync clients without putting those clients in this repository. The main zpan repo owns the server-side sync model, API contract, and protocol tests. OS-specific clients should live in separate projects.

This version is not a CLI version. The CLI from v2.9 is an automation client for agents and scripts; it should not become the internal engine for desktop sync.

Product Boundary

• Community gets the basic sync protocol and device model needed for personal desktop sync.
• Pro / Business may raise device limits or add operator controls later.
• Native desktop/mobile clients are separate projects, such as zpan-desktop or zpan-client.

Why Separate Client Projects

Desktop sync is platform-specific:

• Apple platforms likely need File Provider-style integration.
• Windows has its own shell / cloud-files integration model.
• Linux packaging and filesystem behavior are different again.
• A Flutter app may be a good UI shell, but it has a different toolchain, release process, and platform configuration from this TypeScript full-stack repository.

Keeping native clients outside this repo prevents the server/web project from accumulating unrelated build systems and CI burden.

Major Features

Sync Device Model

Add server-side concepts for sync-capable clients:

• registered devices
• device tokens
• device name, platform, app version, and last seen timestamp
• per-device revocation
• per-space sync authorization
• audit events for device registration and revocation

This is distinct from downloader agents and API keys. A sync device represents a user's file-sync client.

Change Log

Add a durable change stream for object mutations:

• create
• update / replace
• move
• rename
• trash / restore
• delete
• folder operations

Each change should include:

• monotonically increasing sequence or cursor
• org / space id
• object id
• parent id or path context
• actor device id where known
• timestamp
• enough metadata for a client to decide what to fetch next

The change log is the foundation desktop clients need. Do not infer sync state only from current folder listings.

Sync API Contract

Initial API surface:

• Register / revoke device
• Pull changes since cursor
• List remote tree snapshot for bootstrap
• Create upload draft for a sync client
• Complete sync upload
• Apply remote file operations from a device
• Report client sync status and conflicts

The contract should be documented through OpenAPI and covered by integration tests. Client projects should not depend on private frontend RPC helpers.

Conflict Model

Define the server-side conflict contract before client implementation begins.

Default behavior:

• Keep both copies when concurrent edits cannot be reconciled safely.
• Preserve the remote canonical object.
• Store the losing local version as a conflict copy.
• Record conflict metadata for the client UI.

Last-write-wins can be a later opt-in policy, not the default.

Server-Side Status Surface

Add lightweight visibility inside ZPan:

• connected sync devices
• last sync time
• current cursor / status where reported
• recent conflicts
• revoke device

This is not a desktop UI. It is the server-side management surface needed to support external clients.

Protocol Tests And Client Fixtures

Add reusable tests for client implementers:

• initial bootstrap from an empty local folder
• upload local file -> remote object appears
• remote update -> client receives change
• rename / move propagation
• delete / trash propagation
• conflict creation
• revoked device denied

These tests are part of the server contract. They should be usable by separate client projects as conformance references.

Non-goals for v2.10

• Implementing macOS File Provider
• Implementing Windows or Linux desktop sync client
• Implementing Flutter / Tauri / Swift / Kotlin UI
• Using zpan-cli as the desktop sync runtime
• LAN peer-to-peer sync
• Real-time collaborative editing
• LDAP, SCIM, SAML, or enterprise directory synchronization
• Folder-level ACLs or custom roles

User Scenarios

Client developer:

I can build a macOS File Provider client against a documented sync protocol without reading private frontend code.

Self-hosted user:

I can see which desktop devices are connected to my account and revoke an old laptop.

Future desktop app:

The app pulls a change cursor, applies local changes through the sync API, and reports conflicts in a format the server understands.

Future Work

• Separate zpan-desktop / zpan-client project
• macOS File Provider implementation
• Windows cloud-files integration
• Linux desktop integration
• Mobile clients
• Flutter or other cross-platform UI experiments
• Advanced enterprise identity and team governance if demand proves real