Bill Odida.
← Back to Work

Engineering case study · Open-Source Synchronization Toolkit

SyncForge

An open-source offline-first sync toolkit for Flutter and Dart: vector clocks, CRDT primitives, a retryable outbox and durable Drift storage.

DartFlutterCRDTsVector ClocksDrift / SQLitebuild_runnerCode Generation
Architecture Flow · 3 Decoupled Packages
sync_enginePure Dart Core · Vector Clocks · CRDT/LWW Primitives · Outbox Pipeline · In-Memory StoreZero Flutter/Drift dependencies · Testable via plain `dart test`
sync_engine_driftDurable SQLite Persistence · Tombstone Tracking · Persistent Outbox QueueRejects causally stale deletes · Preserves tombstone metadata
sync_engine_generatorCompile-Time build_runner · Automatic SyncAdapter GenerationParses @Syncable, @Id, @ConflictStrategy annotations
todo.dart — @Syncable Model Contract
@Syncable(tableName: 'todos')
class Todo {
  @Id()
  final String id;

  @ConflictStrategy(ConflictResolution.lastWriteWins)
  final String title;

  @ConflictStrategy(ConflictResolution.lastWriteWins)
  final bool isCompleted;

  final VectorClock clock;
  final bool isDeleted;

  Todo({
    required this.id,
    required this.title,
    required this.isCompleted,
    required this.clock,
    this.isDeleted = false,
  });
}

Overview

An open-source synchronization toolkit for Flutter and Dart applications operating under intermittent or offline network conditions. Structured across three decoupled packages: pure Dart core (sync_engine), durable SQLite/Drift persistence (sync_engine_drift), and compile-time code generation (sync_engine_generator).

My Role

Author and maintainer designing the protocol, CRDT primitives, Drift storage adapter, and build_runner generator.

The Problem

Offline-first mobile, desktop, and web applications require deterministic local-write latency and conflict convergence without heavy native runtimes. Distributed updates must remain causally ordered across nodes, deletes must withstand stale replays, and network outboxes must survive process death without request flooding.

Technical Decisions

  • Architected the core engine with zero Flutter or Drift dependencies, making all synchronization and conflict semantics testable via plain dart test
  • Adopted vector clocks for causal ordering alongside field-level conflict strategies (last-write-wins with deterministic node-ID tiebreaking, grow-only counters, and grow-only sets)
  • Implemented tombstone-based deletion with delete-wins semantics for concurrent update-vs-delete operations; Drift storage preserves tombstone metadata and rejects causally stale deletes
  • Built a retryable outbox pipeline featuring exponential backoff, jitter, and dead-letter isolation for poison-pill payloads
  • Created a compile-time code generator using build_runner to produce strongly typed SyncAdapter implementations from @Syncable, @Id, and @ConflictStrategy annotations

Architecture

  • sync_engine (Pure Dart core: contracts, vector clocks, CRDT/LWW primitives, outbox, in-memory store)
  • sync_engine_drift (Durable Drift & SQLite storage engine, outbox persistence, tombstone metadata)
  • sync_engine_generator (build_runner generator producing SyncAdapters from annotations)
  • SyncTransport (Pluggable network transport contract decoupling core logic from backend APIs)

Engineering Highlights

  • Modular three-package architecture separating pure Dart abstractions from platform storage
  • Causal history tracking via vector clocks and field-level CRDT convergence
  • Resilient outbox engine with exponential backoff and dead-letter queue isolation
  • Universal Dart/Flutter platform support: Android, iOS, web, Linux, macOS, and Windows

Results & Impact

  • Published modular packages on pub.dev (sync_engine v0.1.1) supporting 6 platforms
  • 100% pure-Dart core verifiable in headless CI with standard dart test

Scope & Limitations

  • Version 0.1.x: active development status; APIs and schemas continue to be refined toward 1.0
  • The core sync_engine package has no durable persistence on its own; durable storage requires sync_engine_drift or a custom store
  • Backend remains the authority for authentication, authorization, and domain validation
  • The sync_engine_generator rejects custom merge strategies (supports LWW, grow-only counters, and grow-only sets)
  • Storage frontier and tombstone pruning in Drift requires a configured, known replica roster
  • Data encryption at rest and in transit remains the host application's responsibility