Skip to content

sync-architecture.md

Latest commit

 

History

History
70 lines (54 loc) · 2.5 KB

sync-architecture.md

File metadata and controls

70 lines (54 loc) · 2.5 KB

Sync Architecture (platform-agnostic)

This file is shared by mobile-sync-android and mobile-sync-ios. Platform-specific code (Kotlin/Swift) lives in each skill's own SKILL.md.

Architecture

Mobile Device
  └── Couchbase Lite (embedded JSON database)
        │  WebSocket (wss://)
        ▼
  Sync Gateway / Capella App Services
        │
        ▼
  Couchbase Server / Capella

Couchbase Lite syncs over WebSocket. The Sync Gateway (or Capella App Services) mediates access control via the Sync Function. The mobile app always reads and writes locally — replication happens in the background.

Sync Function (Sync Gateway config)

The Sync Function runs server-side in JavaScript. It is not platform-specific.

function sync(doc, oldDoc) {
    // Route to user's private channel
    channel("user." + doc.userId);

    // Require the user to own the document
    requireUser(doc.userId);
}

Key Sync Function APIs:

  • channel(name) — assign document to a channel
  • requireUser(username) — reject write unless the user matches
  • requireRole(role) — reject write unless the user has the role
  • requireAccess(channel) — reject write unless the user has channel access
  • access(username, channel) — grant a user access to a channel

Offline-first pattern

The mobile app always reads and writes to the local Couchbase Lite database. Replication runs in the background — the app never waits for the network.

Design principle: treat the local database as the source of truth. Sync is an implementation detail, not a dependency.

Troubleshooting

Symptom Likely cause Fix
401 on replication Wrong credentials or expired session Re-authenticate; check Sync Gateway logs
Documents not syncing Channel mismatch Verify Sync Function assigns correct channels
Replication stops after idle Network timeout Enable heartbeat in ReplicatorConfiguration
Conflict on every write Two devices writing same doc key Use per-user document keys; see conflict-resolution skill
Large initial sync No delta sync Enable delta sync in Sync Gateway config

Capella App Services vs self-hosted Sync Gateway

Feature Capella App Services Self-hosted Sync Gateway
Setup Managed — no install Manual install + config
Sync Function Supported Supported
Delta sync Enabled by default Requires config
TLS Always on Configurable
Admin API Capella Management API REST on port 4985