Skip to main content

Overview

:::info Source Sourced from services/sync-service/SERVICE_OVERVIEW.md in the documentation repo. :::

1. Purpose​

Offline-first sync protocol. Manages sync registrations, cursors, local mutations, conflict resolution, delta projection. Cross-cutting service enabling offline capability across the platform.

2. Bounded Context​

Offline Sync (Core — competitive differentiator, cross-cutting). UL: SyncRegistration, SyncCursor, LocalMutation, RemoteDelta, VectorClock, ConflictRecord, DeviceBinding.

3. Responsibilities​

  • Expose the sync protocol (/sync/v1/pull, /sync/v1/push, /sync/v1/ack, /sync/v1/resolve-conflict).
  • Maintain per-(tenant, user, device, scope) cursors.
  • Accept local mutations (client → server); route to owning service's push handler.
  • Project server-side deltas from domain events for each registered entity type.
  • Detect and record conflicts per conflict policy (append_only, crdt_yjs, lww, server_authoritative).
  • Expose conflict resolution UI support (manual merge, AI-assisted merge for Yjs).
  • Track device sync health (staleness, connectivity, mutation backlog).

4. Non-Responsibilities​

  • Does not own domain data (each service owns its aggregates).
  • Does not enforce business rules (owning services do via push handlers).
  • Does not manage bundles (content-service does).
  • Does not manage devices (identity-service does).

5. Dependencies​

  • Upstream: every replicable service (registers entity types + delta projectors + push handlers).
  • Upstream: identity-service (device binding verification).
  • Downstream: every replicable service (receives mutations via push handlers).
  • Downstream: analytics-service (sync metrics firehose).

6. Slices & Milestones​

  • S0 (M0): Protocol + cursor + delta framework; sync registrations.
  • S1 (M1): Offline player sync (statements, progress, bundles, enrollments, certificates).
  • S5 (M4): Offline authoring (Yjs CRDTs for live collab + offline edit).
  • S6 (M5): Multi-region sync + mobile native parity.

7. Architectural Freeze Points​

  • F06 — VectorClock semantics (M0 end): never change semantics; additive-only.
  • F07 — Sync protocol (/sync/v1/) (M0 end): additive within v1; breaking → /sync/v2/.

8. Key Invariants​

  • Every mutation anchored to (tenantId, userId, deviceId).
  • Cursors monotonically advancing (never regress unless full-resync).
  • Conflict records immutable after resolution.
  • VectorClock semantics stable (F06).
  • Server-authoritative entities always win on conflict; client mutations rejected post-hoc if server changed.
  • Device must be bound (identity-service verified) before sync allowed.