Cindel Local-First Sync: Adapter, Config, and Offline Writes

Cindel Sync is an experimental local-first replication layer that lets your app keep working offline while automatically reconciling local changes with a backend you control. You write to typed collections as normal; Cindel records those mutations, pushes them to your backend through a CindelSyncAdapter you implement, pulls remote changes, and applies backend corrections back into the local database — all without any code change to your reads or watchers.

What Sync Is and Is Not

Understanding the boundaries of Cindel Sync will save you time when designing your backend. Sync gives you:

Local-first optimistic writes — every write is visible in the local database immediately, before any network round trip.
Offline support — local writes still commit and reads return optimistic data while the device is offline.
Backend corrections applied locally — if your backend normalizes or corrects a document, Cindel applies that truth locally and watchers fire automatically.
A durable outbox — pending mutations survive app close and reopen. When connectivity returns, the scheduler retries automatically.

Sync does NOT provide:

A hosted sync server — you supply the backend.
Conflict resolution rules — your backend decides who wins.
Authentication or access control — your adapter is responsible for auth.
Multi-tab coordination on Web — watcher delivery is single-tab even when sync is active.

Cindel Sync is currently experimental. The adapter contract and configuration API may change between minor releases.

Enabling Sync

Pass a CindelSyncConfig to Cindel.open. Everything else — reads, writes, watchers, transactions — stays the same.

final db = await Cindel.open(
  directory: dir.path,
  schemas: [TodoSchema],
  sync: CindelSyncConfig(
    adapter: MyBackendAdapter(),
    clientId: 'stable-device-id', // must be stable across restarts
    autoStart: true,
    interval: Duration(seconds: 30),
    batchSize: 100,
    onStatusChanged: (status) => print(status),
    onError: (error, stackTrace) => print(error),
  ),
);

After opening, read and write normally. Cindel captures supported local writes automatically — do not create sync mutations by hand.

await db.todos.put(todo);

final all = await db.todos.all().findAll();

final sub = db.todos.watchCollection().listen((todos) {
  // Fires for local optimistic writes and later remote corrections.
});

`CindelSyncConfig` Fields

Field	Type	Description
`adapter`	`CindelSyncAdapter`	Your backend push/pull implementation
`clientId`	`String`	Stable device/user ID — must NOT change across restarts
`autoStart`	`bool`	Whether to start syncing immediately on open
`interval`	`Duration`	Polling interval between sync cycles
`batchSize`	`int`	Max mutations per push batch
`onStatusChanged`	callback	Notified on sync status phase changes
`onError`	callback	Notified on background sync errors

If you omit clientId, Cindel persists an internal ID for this local database. Provide an explicit clientId when your backend needs to track which device sent a mutation — for example, to apply per-device access control or ordering rules.

Sync Status

The onStatusChanged callback receives a CindelSyncStatus object you can use for UI indicators and logging.

final class CindelSyncStatus {
  final CindelSyncPhase phase;
  final int pendingCount;
  final DateTime? lastSyncAt;
  final Object? lastError;
}

The phase field is one of:

Phase	Meaning
`idle`	No sync call is currently running
`syncing`	Cindel is actively calling the adapter
`offline`	The adapter failed with an offline-style error
`error`	The adapter or remote apply failed for another reason

Use pendingCount to show a “2 changes pending” badge. Use lastSyncAt to show a “last synced” timestamp. Always use typed reads and watchers as the source of application data — do not drive UI state from sync callback payloads.

Implementing `CindelSyncAdapter`

Implement the CindelSyncAdapter interface by providing two methods: push and pull.

final class MyBackendAdapter implements CindelSyncAdapter {
  MyBackendAdapter(this.serverBaseUri);

  final Uri serverBaseUri;

  @override
  Future<CindelPushResult> push(CindelPushRequest request) async {
    // Send local mutations to your backend and return the result.
  }

  @override
  Future<CindelPullResult> pull(CindelPullRequest request) async {
    // Fetch remote changes after the local checkpoint and return them.
  }
}

Push Flow

push receives a CindelPushRequest containing the pending local mutations and expects a CindelPushResult in return. CindelPushRequest fields:

clientId — the local client/device ID
lastPulledCheckpoint — the last checkpoint this database pulled
schemaVersionByCollection — current local schema versions by collection name
mutations — the list of CindelSyncMutation objects to send

Each CindelSyncMutation contains:

Field	Description
`mutationId`	Stable ID for retry and deduplication
`clientId`	The client that created the mutation
`sequence`	Local sequence number for this client
`collection`	Collection name, e.g. `todos` or `orderLines`
`operation`	`upsert`, `delete`, or `replaceLinks`
`documentId`	Document ID for document mutations
`document`	Stored document map for upserts
`linkName`	Link name for `replaceLinks` mutations
`targetCollection`	Target collection for `replaceLinks` mutations
`targetIds`	Target document IDs for `replaceLinks` mutations
`baseCheckpoint`	Checkpoint known when this mutation was recorded

Return a CindelPushResult:

return CindelPushResult(
  acceptedMutationIds: {'device-a:1', 'device-a:2'},
  rejectedMutations: [
    CindelSyncRejectedMutation(
      mutationId: 'device-a:3',
      reason: 'product_not_available',
    ),
  ],
  correctedChanges: [
    CindelRemoteUpsert(
      collection: 'todos',
      id: 42,
      document: {
        'dbId': 42,
        'title': 'Buy milk (corrected)',
        'completed': false,
      },
    ),
  ],
  checkpoint: '99',
);

acceptedMutationIds — tells Cindel which pending mutations can be removed from the outbox.
rejectedMutations — for mutations your backend will permanently never accept. Reserve rejections for business failures, not temporary network errors.
correctedChanges — lets your backend return final truth immediately, such as a server-normalized document.
checkpoint — optional on push. If provided, Cindel stores it as the newest known checkpoint.

Pull Flow

pull receives a CindelPullRequest and expects a CindelPullResult containing every remote change after the local checkpoint. CindelPullRequest fields: clientId, checkpoint, collections, schemaVersionByCollection. Return a CindelPullResult:

return CindelPullResult(
  checkpoint: '100',
  changes: [
    CindelRemoteUpsert(
      collection: 'todos',
      id: 7,
      document: {'dbId': 7, 'title': 'From another device', 'completed': false},
    ),
    CindelRemoteDelete(collection: 'todos', id: 3),
    CindelRemoteReplaceLinks(
      collection: 'projects',
      id: 1,
      linkName: 'members',
      targetCollection: 'users',
      targetIds: [10, 11],
    ),
  ],
);

Use resetRequired: true only when the backend cannot safely continue from the client’s checkpoint. For normal incremental sync, leave it as the default false.

The collection field in every remote change must match a schema registered at Cindel.open. Cindel refuses to apply changes for unknown collections.

Offline Behavior

If your adapter cannot reach the server, throw an error from push or pull. Cindel will catch it and retry later according to interval. While offline:

Local writes still commit immediately.
Typed reads return local optimistic data.
Watchers emit local changes.
pendingCount increases as mutations queue in the outbox.
The sync phase may become offline.
Pending mutations survive app close and reopen.

When the server is reachable again, the scheduler retries automatically — no manual intervention required.

Supported Local Operations While Sync Is Active

Cindel records the following local operations as sync mutations:

Typed put and putAll
Typed delete and deleteAll
Query deletes
Link replacements

Query updates (updateFirst / updateAll) are NOT supported while sync is enabled. They do not produce complete document snapshots, so Cindel cannot build a valid mutation from them.Instead of:

// ❌ Not supported with sync enabled
await db.todos.all().updateAll({'completed': true});

Read the objects, mutate them in Dart, then write them back:

// ✅ Correct approach
final todos = await db.todos.all().findAll();
for (final todo in todos) {
  todo.completed = true;
}
await db.todos.putAll(todos);

Minimal Server Requirements

A production sync backend should provide:

Durable storage for accepted mutation IDs and document state.
Idempotent mutationId handling — if the same mutation arrives twice, accept it again without applying it twice.
Stable checkpoints — clients must be able to pull all changes after a given checkpoint reliably.
Access control and authentication — your adapter handles auth; your backend enforces it.
Conflict and correction rules — your backend decides the final document shape.

Start with two endpoints:

POST /sync/push — accepts local mutations, returns accepted IDs and optional corrections.
POST /sync/pull — returns remote changes after a checkpoint.

Testing Sync

Use a FakeSyncAdapter with an online toggle to test sync behavior without a real server. See the Testing page for a full guide.

final adapter = FakeSyncAdapter()..online = false;
final statuses = <CindelSyncStatus>[];

final db = await Cindel.open(
  directory: dir.path,
  schemas: [TodoSchema],
  sync: CindelSyncConfig(
    adapter: adapter,
    interval: const Duration(milliseconds: 10),
    onStatusChanged: statuses.add,
  ),
);

// Local write is visible immediately even while offline.
await db.todos.put(todo);
expect(await db.todos.get(todo.dbId), isNotNull);

// Bring the adapter online and let the scheduler sync.
adapter.online = true;

Common Mistakes

Generating a new clientId on every app start

If your backend uses clientId to track devices or enforce ordering, a new random ID on every launch means every run looks like a brand-new device. Previously sent mutations become orphaned — the backend has no way to deduplicate them. Generate the clientId once, persist it (e.g. in SharedPreferences), and reuse it across restarts.

Updating UI from sync callbacks instead of watchers

The onStatusChanged and onError callbacks are for indicators and logging only. Do not drive application data from their payloads. Use typed Cindel watchers (watchCollection, watchObject, etc.) as the single source of truth for your UI — they fire automatically when remote corrections arrive.

Accepting duplicate mutationIds on the server

Your backend must treat mutationId as an idempotent key. If the network drops after your backend applies a mutation but before the adapter returns, Cindel will retry with the same mutationId. Accepting it twice will corrupt data. Always check whether a mutationId was already applied before processing it again.

Returning remote changes for unregistered collections

Every collection name in CindelRemoteUpsert, CindelRemoteDelete, or CindelRemoteReplaceLinks must match a schema you passed to Cindel.open. If the name doesn’t match, Cindel will refuse to apply the change. Make sure your server only returns collections the client has registered.

Using query updates while sync is enabled

updateFirst and updateAll are not supported when sync is active. They produce partial field patches, not complete document snapshots, so Cindel cannot build a valid mutation. Read the documents, modify them in Dart, and call put or putAll to write them back.

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Cindel Local-First Sync: Adapter, Config, and Offline Writes

What Sync Is and Is Not

Enabling Sync

`CindelSyncConfig` Fields

Sync Status

Implementing `CindelSyncAdapter`

Push Flow

Pull Flow

Offline Behavior

Supported Local Operations While Sync Is Active

Minimal Server Requirements

Testing Sync

Common Mistakes

​What Sync Is and Is Not

​Enabling Sync

​CindelSyncConfig Fields

​Sync Status

​Implementing CindelSyncAdapter

​Push Flow

​Pull Flow

​Offline Behavior

​Supported Local Operations While Sync Is Active

​Minimal Server Requirements

​Testing Sync

​Common Mistakes

What Sync Is and Is Not

Enabling Sync

`CindelSyncConfig` Fields

Sync Status

Implementing `CindelSyncAdapter`

Push Flow

Pull Flow

Offline Behavior

Supported Local Operations While Sync Is Active

Minimal Server Requirements

Testing Sync

Common Mistakes