keep your client up even when the network is down

Offline-first Kotlin Multiplatform SDK that keeps a local data store in sync with a remote server. App code performs data operations through a single API regardless of connectivity — changes persist locally immediately, queue for server transport when offline, and reconcile automatically when connectivity returns. Includes conflict resolution, automatic retries, and periodic sync-down from the server.

This README is optimized for AI agents. For humans, we created something more human optimized: an interactive html walkthrough (ironically, it's agent generated). For an interactive walkthrough covering why buoyient, how it works, and setup guidance, see: explore buoyient >>>

Read the guides in docs/ before writing code. They contain complete templates, required field tables, and common patterns. Use them instead of copying from the example services in this repo (your endpoints, auth, and field names will be different).

The templates/ directory contains copy-ready starter files for the model, request tag, server config, service, and integration test.

Agent instruction files (CLAUDE.md, CODEX.md, .cursorrules, .github/copilot-instructions.md) are also bundled in the published JAR under META-INF/.

1. Define your @Serializable data model implementing SyncableObject<T>
2. Create a ServiceRequestTag enum
3. Implement ServerProcessingConfig<T> (sync-fetch + sync-up + headers)
4. Extend SyncableObjectService<T, Tag> with domain operations
5. Register the service for background sync (Hilt @IntoSet or Buoyient.registerServices())
6. Write integration tests with TestServiceEnvironment

Full walkthrough with templates: docs/creating-a-service.md

Internal packages (managers, sync) are not part of the public API.

These are the rules that cause the most agent errors when missed:

• serviceName must be unique per service — it's the SQLite partition key.

• Constructor takes only 3 required args: serializer (KSerializer<O>), serverProcessingConfig, and serviceName. Internal dependencies are constructed automatically — do not pass them. Optional params: connectivityChecker, encryptionProvider, queueStrategy, rebaseHandler.

• Data models must be @Serializable and implement withSyncStatus(). Mark syncStatus as @Transient — buoyient manages it separately.

• Use placeholder helpers for offline requests:

  • HttpRequest.serverIdOrPlaceholder(serverId) — returns real value when non-null, or {serverId} placeholder resolved at sync time
  • HttpRequest.versionOrPlaceholder(version) — same for version
  • HttpRequest.crossServiceServerIdPlaceholder(serviceName, clientId) — reference another service's server ID in offline requests

• Every operation requires a ServiceRequestTag and uses functional interfaces: CreateRequestBuilder, UpdateRequestBuilder, VoidRequestBuilder, ResponseUnpacker.

• SyncUpConfig.fromResponseBody(requestTag, responseBody) returns SyncUpResult<O>: Success(data), Failed.Retry() (re-queue), or Failed.RemovePendingRequest() (drop from queue).

• SyncableObject companion constants use _KEY suffix: SERVER_ID_KEY, CLIENT_ID_KEY, VERSION_KEY.

• Registration for background sync: use Hilt @IntoSet multibinding with :hilt, or Buoyient.registerServices() / Buoyient.registerServiceProvider() without Hilt.

• Queue strategy: Use Squash when the API uses PUT/replace semantics and intermediate offline states don't matter. Use Queue (default) when request order matters or each write has side effects. See docs/creating-a-service.md § "Pending request queue strategy".

• Cross-service dependencies: Use HttpRequest.crossServiceServerIdPlaceholder(serviceName, clientId) when one service's request references another service's server ID. See docs/creating-a-service.md § "Cross-service dependencies".

• Mock mode and integration testing: Use Buoyient.httpClient and Buoyient.database for global overrides, or TestServiceEnvironment which sets them automatically.

• Do not copy Square-specific values from the example services in this repo. Use the consuming app's endpoints, auth, field names, and base URLs.

testImplementation("com.elvdev.buoyient:testing:<version>")

TestServiceEnvironment provides a fully wired harness — mock HTTP, in-memory DB, controllable connectivity:

@Test
fun `create item online returns server response`() = runBlocking {
    val env = TestServiceEnvironment()

    env.mockRouter.onPost("https://api.example.com/items") { request ->
        MockResponse(201, buildJsonObject {
            put("item", buildJsonObject {
                put("id", "srv-1")
                put("reference_id", request.body["reference_id"]!!)
                put("title", request.body["title"]!!)
                put("version", 1)
            })
        })
    }

    // Service constructor: only required + connectivityChecker for test control
    val service = TodoService(
        connectivityChecker = env.connectivityChecker,
    )

    val result = service.addTodo("Buy milk")
    assertTrue(result is SyncableObjectServiceResponse.Finished.NetworkResponseReceived)
    assertEquals(1, env.mockRouter.requestLog.size)

    service.close()
}

Toggle offline: env.connectivityChecker.online = false

Full testing guide: docs/integration-testing.md | Mock mode guide: docs/mock-mode.md

• Offline-First — Create, update, and void data locally when offline. Changes queue and sync when connectivity returns.
• Bidirectional Sync — Periodic sync-down (server to local) and on-demand sync-up (local to server).
• 3-Way Merge & Conflict Resolution — Field-level conflict detection with pluggable merge policies via SyncableObjectRebaseHandler.
• Pending Request Queue — Persisted to SQLite, survives app restarts, supports idempotency keys.
• Placeholder Resolution — {serverId} and {version} placeholders resolved at sync time for safe offline chaining.
• Request Tagging — ServiceRequestTag enums for per-operation response handling.

buoyient is distributed to iOS projects as an XCFramework via Swift Package Manager:

# Build the framework
./gradlew :syncable-objects:assembleBuoyientReleaseXCFramework

The framework includes SKIE integration, which automatically provides Swift-native APIs: suspend -> async/await, sealed class -> Swift enum, Flow -> AsyncSequence.

See docs/setup-ios.md for the complete iOS setup guide.

./gradlew :syncable-objects:build
./gradlew :hilt:build
./gradlew :testing:build

Build iOS XCFramework:

./gradlew :syncable-objects:assembleBuoyientReleaseXCFramework

Run tests:

./gradlew :syncable-objects:jvmTest
./gradlew :mock-infra:jvmTest
./gradlew :mock-mode:jvmTest
./gradlew :testing:jvmTest

Publish to local Maven:

./gradlew :syncable-objects:publishToMavenLocal
./gradlew :hilt:publishToMavenLocal
./gradlew :testing:publishToMavenLocal