Offline Sync Engine #

Offline-first CRDT-based sync engine for Flutter and Dart applications. It keeps data synchronized across devices with deterministic conflict resolution.

Features #

• 🔄 Automatic Sync - Push local operations and pull remote operations.
• 📴 Offline-First - Create/update/delete records without network.
• 🔀 Deterministic Merge - Concurrent updates converge predictably.
• 📱 Multi-Device - Same account on multiple devices stays in sync.
• 🎯 Operation-Based - Sync is based on replayable operations.
• 🔢 Vector Clocks - Causality tracking across devices.
• ⚡ Idempotent Apply - Safe against duplicate operation delivery.
• 🧩 Adapter-Based - Plug in your own database and cloud backend.
• ✅ Type Safe - Null-safe Dart API.

Architecture #

┌─────────────────────────────────────────────────────────────┐
│                        Your App                             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                     SyncManager                             │
│  - createOrUpdate()                                         │
│  - delete()                                                 │
│  - sync()                                                   │
└────────────┬────────────────────────┬───────────────────────┘
             │                        │
             ▼                        ▼
┌────────────────────────┐  ┌────────────────────────┐
│   DatabaseAdapter      │  │    CloudAdapter        │
│  (Your Implementation) │  │  (Your Implementation) │
│                        │  │                        │
│  - SQLite              │  │  - REST API            │
│  - Hive                │  │  - Firebase            │
│  - SharedPreferences   │  │  - Supabase            │
│  - ObjectBox           │  │  - GraphQL             │
└────────────────────────┘  └────────────────────────┘

Installation #

dart pub add offline_sync_engine

or

flutter pub add offline_sync_engine

Your pubspec.yaml:

dependencies:
  offline_sync_engine: ^3.0.0

Then run:

dart pub get

or

flutter pub get

Quick Start #

import 'package:offline_sync_engine/offline_sync_engine.dart';

void main() async {
  final manager = SyncManager(
    database: InMemoryDatabaseAdapter(),
    cloud: InMemoryCloudAdapter(),
    deviceId: 'device_123',
  );

  // Local write (works offline)
  await manager.createOrUpdate('user_1', {
    'name': 'John',
    'email': 'john@example.com',
  });

  // Push + pull sync
  await manager.sync();
}

Core Concepts #

1) Adapters #

You provide two adapters:

1. DatabaseAdapter: local persistence (SQLite, Hive, Isar, etc.)
2. CloudAdapter: backend transport (REST/Firebase/Supabase/etc.)

For demos/tests, use built-ins:

• InMemoryDatabaseAdapter
• InMemoryCloudAdapter

2) SyncManager #

SyncManager is the main entry point:

final manager = SyncManager(
  database: myDatabaseAdapter,
  cloud: myCloudAdapter,
  deviceId: 'unique_device_id',
);

await manager.createOrUpdate('note_1', {'title': 'hello'});
await manager.delete('note_1');
await manager.sync();

final syncing = manager.isSyncing;

3) Conflict Resolution #

The engine uses vector clocks with deterministic merge:

• If one version dominates another, dominant record wins.
• If versions are concurrent, fields are merged deterministically.
• Merge result is stable and commutative for concurrent records.

Production Checklist (Important) #

Before publishing your app with custom adapters:

• ❌ Ensure saveOperation + applyOperation are durable.
• ❌ Keep operation IDs unique and indexed.
• ❌ Make isApplied fast (index/table/set).
• ❌ Use retries/backoff for cloud calls.
• ❌ Add authentication/authorization at transport layer.
• ❌ Add pagination/incremental pull strategy on backend.
• ❌ Add monitoring for sync failures.

Running Examples #

cd example
dart run main.dart
dart run multi_device_example.dart
dart run delete_example.dart
dart run custom_adapters_example.dart

More details: example/README.md

Adapter Contract Notes #

DatabaseAdapter expectations #

• saveOperation should persist operation before app crash risk.
• getUnsentOperations should return unsent operations reliably.
• markOperationSent should be idempotent.
• isApplied should be idempotency source-of-truth.
• applyOperation must be deterministic and safe to replay.

CloudAdapter expectations #

• push should accept duplicate deliveries safely.
• pull can return already-seen operations; manager handles dedupe via isApplied.
• Server ordering should be stable where possible.

License #

MIT License - see LICENSE.