Offline-first sync engine for Kotlin Multiplatform — outbox, push/pull, and conflict policy on top of your entity store.

Latest on Maven Central: 2.0.0 · Changelog · Upgrade from 1.1.0
Monorepo (main): 2.0.1 — Integration DX (BYO store + transport APIs stable); Changelog § 2.0.1. Not on Central until published — install pins stay at 2.0.0.

SyncForge is a client-side sync engine, not a hosted backend or a replacement for Room/SQLDelight/Realm.

Local writes go to your store first (optimistic). Mutations enqueue; sync drains the outbox when the network is available. Offline edits and app restarts are first-class.

UI / navigation: SyncForge is not a navigation or MVI framework. For Compose multiplatform navigation and sync-aware chrome, see ForgeNav (studio.forgenav).

Good fit when you need:

• Offline-first mobile (or multiplatform) apps with your own API
• An outbox that survives process death, with explicit sync() / scheduled sync
• Per-entity conflict strategies without rewriting a sync stack
• Android-first delivery, with iOS / JVM desktop / macOS on the same model
• Self-hosted or BYO backend (Ktor/Spring starters and a mock server are in-repo)

Not a fit when you want:

• A managed BaaS that owns your schema and auth end-to-end (use Supabase/Firebase as a transport, or pick a full BaaS product)
• Automatic domain schema evolution for breaking JSON changes (you migrate Room + payloads; SyncForge does not version your entity model)
• Real-time collaborative editing as the primary mode (push/pull + optional realtime adapters; not a full CRDT document product)
• Drop-in Swift Package Manager / XCFramework install today (use KMP frameworks via Gradle — iOS setup)
• Production browser install from Maven Central (web is experimental and monorepo-only — Web setup)

Wire format: REST v1 (POST /sync/push, GET /sync/pull) is frozen for the 2.x line. Entity payload schemas are your domain, not SyncForge semver. Details: REST_API.md, MODULES.md (stability table).

./gradlew :mock-server:run          # Terminal 1 — reference API on :8080
./gradlew :sample:installDebug      # Terminal 2 — emulator uses http://10.0.2.2:8080

In the sample: Sync, force a conflict, or clear local data and pull. Debug builds expose an SF overlay for outbox depth and sync health.

Import the version catalog once (2.0.0 pins every artifact and the Gradle plugin):

// settings.gradle.kts
dependencyResolutionManagement {
    versionCatalogs {
        create("syncforge") {
            from("studio.syncforge:syncforge-catalog:2.0.0")
        }
    }
}

// app/build.gradle.kts
plugins {
    alias(syncforge.plugins.syncforge.android)
}
dependencies {
    implementation(syncforge.core)
}

// Application
syncManager = SyncForge.android(this) {
    baseUrl("https://api.example.com")
    registry(SyncForgeHandlers.registry(taskDao))
    schedulePeriodicSyncOnStart()
}

// Repository — write your DB, then enqueue
syncManager.enqueueChange(Change.create("tasks", task))
syncManager.sync()

Full walkthrough (~10 min): Getting Started
iOS / desktop: iOS setup · Desktop setup

Gradle snippets and DSL options live in the setup guides — not duplicated here.

These are intentional product boundaries, not temporary bugs:

1. Entity schema is yours — SyncForge stores opaque payloadJson. Additive JSON changes are straightforward; breaking renames/refactors need your Room migration and a plan for pending outbox / server history. There is no built-in schemaVersion migrate API yet.
2. You need a backend (or adapter) — SyncForge does not host data. Implement the push/pull contract or use a provided transport against Supabase/Firebase/GraphQL.
3. Not whole-document CRDT collab — Field-level crdt { } / gitLike { } help merge concurrent edits; they are not a Notion-style collaborative document layer.
4. iOS install path — KMP framework from Gradle today; SwiftPM / XCFramework packaging is still on the roadmap.
5. Web is experimental — not published to Central; SQL.js worker stack; opt-in required.
6. Optional modules are non-transitive — store, transport, and integration artifacts are listed in the catalog; add them explicitly when needed.
7. Multi-device E2E and samples prove the engine — production hardening (auth, rate limits, observability) is documented; your ops and threat model remain yours.

Deeper guidance: Best practices · Conflict resolution · Roadmap.

Contributing and local verification: CONTRIBUTING.md.

git clone https://github.com/Arsenoal/syncforge.git
cd syncforge
./gradlew verifyReleaseSignOff

Apache License, Version 2.0