Architecture and Specs

SynckHub is split into clear service boundaries.

Primary components

SynckHub platform: data-plane APIs and item operations
Common control plane: auth, tenancy, directory, routing, and snapshots
Federation Clearinghouse: federation authority domain
SynckHub Desktop: separate client runtime for local editing and OS-native workflows

Contract sources

For implementation truth, start with these internal contracts:

SynckHub platform spec
SynckHub authz spec
Common control plane spec plus OpenAPI
federation authority and registry specs
mail, calendar, structured-data, WOPI, Yjs, and shared-link specs when your feature area needs them

Design constraints to keep in mind

Common is not in the hot path for normal repo data operations
access JWTs carry identity, not full authorization decisions
directory and snapshot caching are required for resilience
desktop integrations are real product surfaces, not test harnesses

Practical map for integrators

Use this decision rule:

Need sign-in, tenant identity, repo routing, or infra metadata? Start in Common.
Need repository items, permissions, versions, content, search, or audit? Start in SynckHub.
Need cross-instance trust or replicated authority flows? Start in federation contracts.

Product-model warning

Do not assume every visible workspace object is a peer item type.

In the current product:

companies and cases can be folder-backed work records; contacts are record-backed people data
mail and calendar surfaces are explorer-owned workflows over connected-account data
repo directory pages are governance routes, not ordinary content views