Mosaic

Server-Driven UI framework for Kotlin Multiplatform

Mosaic is a Server-Driven UI framework: the backend describes a screen — its components, layout, styling, data bindings and interaction logic — as a serialized tree, and the client (Android, iOS, Desktop, Web) deserializes and renders it live with Compose Multiplatform. There is no per-platform UI code to write for a new screen and no client build to ship when a screen changes.

This is a personal project, built and maintained by one person, and it is under active development. Some subsystems (persisted data, offline caching, a few event/tile combinations) are still being reworked; the architecture and everything documented below is implemented and runnable, not aspirational. The current focus and open items are tracked in ROADMAD.md.

A native client and a JSON-over-HTTP backend agree on a fixed UI contract at build time. Changing that contract — adding a field to a form, reordering a screen, changing what a button does on success versus failure — means shipping new client code, through app store review, on every platform you support. If you support Android, iOS, desktop and web from one team, you're maintaining the same screen logic four times.

Server-Driven UI moves that contract from build time to request time. The client stops hardcoding screens and becomes a generic interpreter for a fixed vocabulary of components (Tiles) and behaviors (Events). The backend team owns screen composition, conditional logic, network orchestration and navigation, in Kotlin, and ships changes without touching the client binary.

Mosaic is a full implementation of that idea: a shared type-safe contract (mosaic-core), a backend DSL to build that contract (mosaic-server), and a rendering/execution engine that consumes it (mosaic-client).

All three modules are published to Maven Central under dev.catbit. mosaic-core holds the shared Schemas that both the server DSL and the client renderer are built on, and it's declared as an implementation (not api) dependency on both sides — add it explicitly alongside whichever module you're pulling in.

gradle/libs.versions.toml

[versions]
mosaic = "1.0.0"

[libraries]
mosaic-core = { module = "dev.catbit:mosaic-core", version.ref = "mosaic" }
mosaic-server = { module = "dev.catbit:mosaic-server", version.ref = "mosaic" }

build.gradle.kts

dependencies {
    implementation(libs.mosaic.core)
    implementation(libs.mosaic.server)
}

Or with direct coordinates:

dependencies {
    implementation("dev.catbit:mosaic-core:1.0.0")
    implementation("dev.catbit:mosaic-server:1.0.0")
}

That's the whole backend footprint — mosaic-server is a plain JVM library, no Ktor server required by the DSL itself (sample-server just happens to use Ktor to expose it over HTTP).

gradle/libs.versions.toml

[versions]
mosaic = "1.0.0"

[libraries]
mosaic-core = { module = "dev.catbit:mosaic-core", version.ref = "mosaic" }
mosaic-client = { module = "dev.catbit:mosaic-client", version.ref = "mosaic" }

build.gradle.kts (inside a Compose Multiplatform module's commonMain source set)

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.mosaic.core)
            implementation(libs.mosaic.client)
        }
    }
}

Or with direct coordinates:

commonMain.dependencies {
    implementation("dev.catbit:mosaic-core:1.0.0")
    implementation("dev.catbit:mosaic-client:1.0.0")
}

mosaic-client targets Android, iOS (iosArm64/iosSimulatorArm64), Desktop (jvm) and Web (wasmJs) — pick whichever of those your Compose Multiplatform module already targets, nothing extra to configure per-platform. mavenCentral() needs to be in your dependencyResolutionManagement/repositories block, same as any other Central-hosted dependency.

// mosaic-server
Screen(id = "login") {
    Column {
        TextField(id = "email", label = "Email")
        TextField(id = "password", label = "Password", visualTransformation = passwordTransformation())

        Button(
            id = "submit",
            text = "Sign in",
            events = {
                SendNetworkRequest(
                    trigger = EventTriggers.onClick(),
                    url = "/api/login",
                    method = HttpMethod.POST,
                    events = {
                        UpdateData(
                            trigger = EventTriggers.onSuccess(),
                            updates = {
                                update(
                                    dataSource = applicationSegmentedData("auth"),
                                    updateData = explicitIncomingUpdateData(dataId = "session")
                                )
                            },
                            events = {
                                Navigate(trigger = EventTriggers.onSuccess(), destination = "home", navigatorId = "root")
                            }
                        )
                        DisplaySnackbar(trigger = EventTriggers.onFailure(), message = "Login failed")
                    }
                )
            }
        )
    }
}

Nothing in that tree references platform code. The client that renders it doesn't know "login" exists ahead of time — it knows how to render a Column, a TextField, a Button, and how to run SendNetworkRequest → UpdateData → Navigate/DisplaySnackbar as a chained event graph, because those are part of the fixed vocabulary shipped in mosaic-core/mosaic-client. Event chaining is driven entirely by trigger matching (onSuccess(), onFailure(), ...) on each node's events field — there's no callback wiring on the client side to write.

Bootstrapping a client is a single composable:

// mosaic-client (Compose entry point)
MosaicApplication(
    applicationId = "MyApp",
    baseUrl = "https://api.example.com",
    appSplash = { Text("Loading…") }
)

46 typed Tile schemas, covering everything a Material 3 screen typically needs. Every tile — regardless of category — shares a base contract: id, events, style (size/margin/padding/background/border/clip/window insets), visibility (VISIBLE/INVISIBLE/GONE), and searchableTerms (used by parent containers to filter children).

Text

Buttons

Chips

Inputs

Images & icons

Containers & layout

App bars

Navigation

Progress

Feedback & overlays

System

57 typed Event schemas. Every event shares id, trigger (the EventTrigger that fires it) and events (children dispatched by trigger once this event completes) — which is what makes chaining work: SendNetworkRequest → onSuccess() → UpdateData → onSuccess() → Navigate is one declarative tree, no glue code. Roughly 70 EventTrigger types exist to key that dispatch (OnClick, OnSuccess, OnFailure, OnStart, plus scroll, keyboard, lifecycle, permission and network-state triggers).

Tile management

Navigation

Screen

Data

Networking

File system

Overlays

Meta, menu & popup

Time & scroll

Security & system

Theme

Two storage tiers, each with plain (flat key-value) and segmented (bucketed) variants:

• In-memory, scoped to either the current screen or the whole application session.
• Persistent, backed by SQLDelight (multiplatform SQLite).

GetData, UpdateData and RemoveData read and write both tiers with Full/Single/Batch access modes. Values round-trip as real nulls where the storage tier supports it — a form field that's intentionally empty, or an optional API response field, stays null end to end instead of collapsing into "key missing," including when it's serialized straight into a SendNetworkRequest body.

Consumers of mosaic-client register their own Tiles and Events without forking the framework:

MosaicApplication(
    applicationId = "MyApp",
    baseUrl = "https://api.example.com",
    dependencyInjectionConfig = mosaicDependencyInjectionConfig(
        tileDefinitions = listOf(MyCustomTileDefinition),
        eventDefinitions = listOf(MyCustomEventDefinition),
        additionalSerializersModule = myCustomSerializersModule
    ),
    appSplash = { }
)

Custom schemas plug into the same MosaicSerializer polymorphic registry and the same Definition → Renderer/Runner lookup as everything shipped in mosaic-core.

Every Tile and Event follows the same three-layer split:

mosaic-core   — shared Schemas, MosaicSerializer (polymorphic JSON)
    ↑
    ├── mosaic-server   — Kotlin DSL, builds and serializes screens
    ├── mosaic-client   — deserializes, renders (Compose Multiplatform), runs events
    ├── sample-server   — reference Ktor backend
    └── sample-client   — reference Android/Desktop client

# Ktor backend, serves sample screens on :9090
./gradlew sample-server:run

# Desktop client
./gradlew sample-client:run

# Everything
./gradlew build

Apache License 2.0.