Skip to content

docs: define primary sync provider architecture - #27

Open
AiraAgent wants to merge 5 commits into
mainfrom
docs/primary-sync-provider
Open

docs: define primary sync provider architecture#27
AiraAgent wants to merge 5 commits into
mainfrom
docs/primary-sync-provider

Conversation

@AiraAgent

@AiraAgent AiraAgent commented Aug 1, 2026

Copy link
Copy Markdown
Collaborator

Summary

Document the accepted primary sync-provider architecture for Daily:

  • one active bidirectional provider per workspace: iCloud Drive or a self-hosted server compatible with the Daily Sync Protocol;
  • local SQLite remains the offline working database, while the selected provider is the shared synchronization authority;
  • a shared provider binding contains provider kind, stable server identity, workspace ID, public endpoint, and identity-provider metadata;
  • a new device verifies that server identity, signs in locally, and joins the existing workspace rather than choosing another writable provider;
  • after initial server claim, a personal device joins through browser authentication and workspace membership—never through server-console access or another claim code;
  • LocalSyncSettings remain device-local: access/refresh tokens, device ID and private keys, local paths, and transient connection state are never synchronized;
  • the server recognizes devices as members of one workspace through server identity, workspace ID, authenticated account membership, and individual device records—not shared tokens or keys;
  • a provider mismatch blocks bidirectional sync rather than allowing iCloud and a custom backend to become separate writable authorities;
  • self-hosted servers require a versioned protocol, revision-aware writes, client-side merge, and controlled provider migration;
  • the official server requires guided first-run setup and a Desktop connection wizard;
  • modern authentication is explicit: browser OAuth Authorization Code + PKCE, Device Authorization Grant for CLI/headless clients, and passkeys as the primary embedded sign-in method.

Validation

  • Reviewed the five published commits and their complete patches.
  • Changed-file scope: one architecture document, 96 additions across five commits.
  • Verified docs/primary-sync-provider resolves to f3e8db806bdb5909daafb31b4349b5e21a344e9a on the remote.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant