Implementing Conflict-Free Sync in Mobile Apps with Y.js and Automerge

From our experience, conflicts during synchronization cause nearly 70% of errors in collaborative mobile apps. For example, one of our clients, a fintech company, had 8 users editing the same document simultaneously via REST sync, leading to data loss. After we implemented Y.js, sync incidents dropped by 95%, saving the client an estimated $30,000 in server costs over six months. We'll assess your project for free within 24 hours. Our engineers are certified developers with 7+ years of experience in offline-first architectures.

CRDT (Conflict-free Replicated Data Types) mathematically guarantee that any two replicas of the same document receiving the same operations in any order will converge to identical state. No coordinating server. No manual conflict resolution. This is especially valuable for mobile apps: edit offline on the subway, sync at home, merge automatically and deterministically.

What Are CRDTs in Practice

It's not one algorithm but a family of data structures, each solving a specific problem:

• G-Counter – counter that only grows. Merge = max per node.
• LWW-Register (Last-Write-Wins) – single value, last timestamp wins. Suitable for individual fields (document title, status).
• OR-Set (Observed-Remove Set) – set with add and remove. Resolves "deleted while partner added simultaneously" via unique tags for each add operation.
• RGA (Replicated Growable Array) – array with insert/delete. Foundation for text CRDTs.
• YATA (Yet Another Transformation Approach) – Y.js algorithm, a variant of RGA.

Y.js: Detailed Breakdown

Y.js is the most mature CRDT implementation for JavaScript/TypeScript. It uses YATA for YText and YArray, LWW for YMap. Y.js outperforms Automerge by about 2x in text-heavy applications.

Internal structure of YText: linked list of Items, each with id: {client, clock}. client – unique clientID (uint32, generated on Y.Doc creation). clock – logical clock, monotonically increasing per client. Merging two YDocs = union of all Items with deterministic ordering on conflict (smaller clientID first at same logical time).

Key: operations never get lost. Even if an insert happened offline on one device while another simultaneously deleted surrounding text, the insert will apply — it might end up in an "empty" spot, but it won't be lost.

How Synchronization Works with Y.js?

Y.js is only the algorithm. Transport is a separate provider:

For mobile apps: y-websocket for online sync + custom provider for SQLite (device persistence). Ready y-sqlite for React Native doesn't exist — we implement via Y.encodeStateAsUpdate() and Y.applyUpdate() with storage in react-native-sqlite-storage.

// Save to SQLite on every change
ydoc.on('update', (update, origin) => {
  if (origin !== 'sqlite') {  // don't save changes from SQLite
    const state = Y.encodeStateAsUpdate(ydoc);
    db.executeSql('INSERT OR REPLACE INTO docs (id, state) VALUES (?, ?)',
      [docId, Buffer.from(state).toString('base64')]);
  }
});

// Load on document open
const [result] = await db.executeSql('SELECT state FROM docs WHERE id = ?', [docId]);
if (result.rows.length > 0) {
  const state = Buffer.from(result.rows.item(0).state, 'base64');
  Y.applyUpdate(ydoc, new Uint8Array(state), 'sqlite');
}

Automerge: An Alternative to Y.js

Automerge is a CRDT library with a different approach: document is a JSON object with deep merge semantics. Automerge 2.x rewritten in Rust, compiled to WASM — performance an order of magnitude higher than v1.

For React Native: @automerge/automerge works via WASM in JSC/Hermes. On Hermes — must verify WASM support (recent RN Hermes supports WASM but not all builds).

Advantage over Y.js: data schema is plain JSON, not special types. But Y.js has more active support and more sync providers. Performance tests show Y.js is ~2x faster for text collaboration.

How to Choose Between Y.js and Automerge?

Choose based on data type and platform. Compare key characteristics:

How to Implement CRDT Sync in 5 Steps

1. Choose a CRDT library: Y.js for text-heavy apps or Automerge for JSON-centric data.
2. Set up local persistence: Store state as base64-encoded snapshots in SQLite or IndexedDB.
3. Integrate a sync provider: Use y-websocket for server-backed sync or y-webrtc for P2P.
4. Implement conflict awareness UI: Notify users when conflicts are automatically resolved (e.g., 'Your edit was merged with another' ).
5. Test with offline scenarios: Simulate network loss and concurrent edits to verify convergence.

What Are Vector Clocks and How Do They Help?

Y.js automatically tracks stateVector — map of {clientId: maxClock}. When syncing two replicas:

1. Exchange stateVector.
2. Request Y.encodeStateAsUpdateV2(ydoc, remoteStateVector) — delta from what remote side doesn't know.
3. Apply delta via Y.applyUpdateV2().

This enables efficient sync without transferring full document. On reconnect after offline: send own stateVector, receive only missing changes.

Convergence: What CRDT Guarantees – and What It Doesn't

CRDT guarantees Strong Eventual Consistency: if all replicas receive the same operations – they converge to identical state.

Semantic correctness is not guaranteed. If user A renamed file to "Report Q1" while user B deleted it, CRDT may restore the file with new name. Mathematically correct (add wins over remove in OR-Set), but semantically surprising for the user.

Solution: UX layer that informs user of the conflict and its automatic resolution – don't break work, but provide visibility.

Performance with Large Documents

Y.js lazy-loads document structure: parts not requested are not decoded. Important for documents 1MB+. Y.Doc with gc:true (default) automatically removes tombstone entries of deleted elements, compressing history.

With many edits, operation history grows. Y.encodeStateAsUpdate() contains all changes since creation. Compaction via Y.encodeStateAsUpdate(ydoc, emptyStateVector) – snapshot of current state without history. For offline apps: store snapshot + delta after snapshot.

What's Included in CRDT Implementation Work

• Requirements analysis and sync architecture design
• Protocol selection (Y.js, Automerge, or custom solution)
• Integration with local storage (SQLite, PostgreSQL)
• Sync provider implementation (WebSocket, WebRTC)
• Writing conflict and performance tests
• Preparing documentation and team training
• One month post-production support

Estimates

CRDT sync via Y.js for text/JSON documents in React Native – 6–10 weeks (including persistence, reconnect logic, conflict awareness UI). For Flutter via Dart bindings to Y.js (through JS runtime) or native CRDT – 10–16 weeks. Automerge 2 on Rust FFI for native platforms – 12–20 weeks. Server infrastructure savings can reach 60% compared to traditional methods. The budget typically ranges from $5,000 to $25,000 depending on complexity. Over 90% of conflicts are automatically resolved using CRDT, reducing manual merge efforts by up to 80%. Contact us for a free estimate – get a consultation from an engineer within one business day. For more details on the CRDT specification, see Wikipedia and Y.js documentation.

How to Start Integrating API into a Mobile App?

The request goes out, the response doesn't come, timeout — 30 seconds. The user stares at the spinner. No network — mobile card in the subway. Or the network is there, but the server returns 200 with an HTML error page instead of JSON — and the app crashes on JSONDecoder.decode(). We see such cases on every second project. So integrating API into a mobile app is not just calling an endpoint, but designing a reliable network layer: error handling, caching, offline mode, certificate pinning. Order an audit of your current network layer — we will evaluate the project in 1 day. Our team guarantees a thorough analysis and provides a detailed roadmap.

Standard libraries like URLSession and OkHttp provide basic HTTP clients, but for production you need retries with exponential backoff, status code validation, typed deserialization, and network state monitoring. Without this, the app loses data and users. We have been doing mobile development for 5 years and implemented more than 30 projects with API integration on iOS, Android, and Flutter — from startups to enterprise solutions.

How to Choose a Protocol for API Integration?

REST remains the standard for most projects. But when a profile screen needs 5 fields out of 40, GraphQL eliminates over-fetching and reduces traffic by 30–60%. gRPC is justified for thousands of requests per minute (trading, IoT) — binary serialization is 3–5 times faster than JSON. WebSocket is the only choice for real-time without polling (messages, notifications).

Practical example: For a fintech app, we replaced REST (40 fields) with GraphQL — response size dropped from 12 KB to 2.5 KB, screen render time decreased by 70%. Traffic savings were significant. Our certified iOS and Android developers have deep experience with all these protocols — you can rely on proven solutions.

How to Ensure Reliable Connection and Offline-First?

Users lose network in the subway, elevator, tunnel. A mobile app must work without internet — at least in read-only mode. We implement the offline-first pattern:

1. On screen open, first show data from the local cache (Core Data / Room).
2. Simultaneously perform a network request, update UI after response.
3. If network is unavailable — show cached data and a 'no connection' label.
4. When network is restored, automatically synchronize changes.

For HTTP response caching we use URLCache (iOS) and OkHttp Cache (Android) with Cache-Control support. For structured data — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback monitor network state and trigger updates.

REST and Client Library Selection

Alamofire (iOS) — de facto standard for Swift projects. On top of URLSession it adds request chaining, response validation, automatic retry, certificate pinning via ServerTrustManager. AF.request() with .validate() returns an error for any status code outside 200–299. Without .validate(), Alamofire considers 404 and 500 as successful responses. With Swift Concurrency — async version via serializingDecodable.

Retrofit (Android) — annotation-based HTTP client on top of OkHttp. An interface with annotations compiles into implementation. @GET, @POST, @Path, @Query, @Body — declarative API description. OkHttp under the hood: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — logging in debug builds. Authenticator — automatic token refresh on 401.

Ktor (KMM/Flutter) — multiplatform HTTP client. On iOS it works via Darwin engine (URLSession), on Android — via OkHttp. Single code for both platforms with KMM architecture.

GraphQL: When REST Falls Short

REST returns a fixed structure. A profile screen needs name, avatar, email — the server sends 40 fields. Over-fetching. GraphQL solves this: the client requests exactly the needed fields. This is critical for mobile where traffic and parsing time are real constraints. Apollo iOS and Apollo Kotlin generate typed classes from schema: schema.graphql + query files → strict types at compile time. Subscriptions via WebSocket — real-time without polling. Limitation: GraphQL is harder to cache at the HTTP level. Apollo uses a normalized in-memory cache InMemoryNormalizedCache — requests with overlapping data update the cache without duplication.

WebSocket: Real-Time Without Extra Traffic

Polling (setInterval every 5 seconds) — battery and traffic waste. WebSocket is a persistent bidirectional connection. iOS: URLSessionWebSocketTask (native, iOS 13+). Android: OkHttp WebSocket. Mandatory reconnect handling: on onFailure — exponential backoff (1s → 2s → 4s → 8s → max 60s). Socket.IO is an overlay with automatic reconnect, but for new projects native WebSocket is preferable (fewer dependencies).

gRPC: For High-Load Services

gRPC with protobuf — binary serialization: smaller size, faster parsing. grpc-swift for iOS, grpc-kotlin for Android. The protobuf schema compiles to typed classes. Streaming (server-side, client-side, bidirectional) is a native feature. Application threshold: high request frequency (trading, IoT) or critical latency. For regular CRUD, REST is simpler to debug and monitor.

Certificate Pinning and Security

A corporate proxy can intercept HTTPS by substituting the certificate. Certificate pinning prevents this: the app accepts only a specific certificate or public key. Alamofire: ServerTrustManager with PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner with SHA-256 hash. Apple's App Transport Security documentation recommends pinning certificates for sensitive data. Operational complexity: on certificate rotation, older app versions stop working. Solution — pinning to the CA public key or support multiple pins with a grace period.

What Is Included in the Work

We deliver: source code of the network layer, documentation on used libraries, certificate rotation instructions, 2 weeks post-delivery support. Our experience guarantees that the solution will be stable and maintainable.

Timeline and Cost

Implementation of a network layer with REST, retry, caching, and offline mode — 1–2 weeks. Adding GraphQL or WebSocket — another 1–2 weeks. gRPC — 2–3 weeks, including code generation. The cost is calculated individually after analyzing the API and offline behavior requirements. We will evaluate the project in 1 day — contact us for a consultation. Get a reliable API integration with guaranteed quality.