What is Mosaic?
Mosaic is a Kotlin library for building backends one response at a time. Start with the data your endpoint returns, then compose the work that produces it. Mosaic works alongside any HTTP framework, including Spring Boot, Ktor, and Micronaut. Your framework still owns routing, serialization, and server lifecycle; see the runnable framework examples.
A Tile is a reusable piece of suspending work. It can read dependencies and compose other Tiles. A Mosaic executes those Tiles, sharing repeated work within that instance. A Canvas supplies application services and request input. A MultiTile does keyed work with reuse and opportunistic batching.
val OrderPageTile by singleTile { val summary = composeAsync(OrderSummaryTile) val logistics = composeAsync(LogisticsTile) OrderPage(summary.await(), logistics.await())}The example uses the models and dependencies in the shared order library. Summary and logistics can run concurrently. Each branch asks for its own requirements; repeated requests for the same Tile share one execution.
Learn how Tiles form a dynamic dependency graph as the response is composed.
When it helps
Section titled “When it helps”Mosaic fits responses assembled from multiple services, graphs with shared dependencies, and keyed fetches used by independent branches. It keeps that orchestration close to the response logic and makes the same compositions easy to test in isolation.
A backend-for-frontend (BFF) API is one such use case: compose data for a web or mobile client from several backend services without duplicating work shared by different response parts.
For a single service call, ordinary suspending Kotlin may already be sufficient. Mosaic adds a runtime cost that depends on the graph; inspect the performance evidence for your workload.
Follow a Kotlin API aggregation example to build one response from multiple services and share dependencies across its branches.
Runtime first, tooling optional
Section titled “Runtime first, tooling optional”No registration plugin or processor is needed for runtime use. Add the core library and write ordinary Kotlin. Testing and OpenTelemetry support are optional runtime modules. Compiler analysis is separate build tooling with a narrower compatibility boundary.
Install Mosaic, then follow the Quick Start. For exact signatures, use the Kotlin API.
Evaluate adoption
Section titled “Evaluate adoption”Check runtime and optional analysis requirements against your application’s toolchain. Review the release notes and 0.x upgrade guidance before choosing a version. Mosaic is licensed under Apache 2.0.
Maintainer and support
Section titled “Maintainer and support”Mosaic is maintained by Nicholas Abbott (nick@buildmosaic.org). Use GitHub Issues for usage questions, bug reports, and feature requests. The contribution guide explains contribution and discussion routes.
Report vulnerabilities privately to security@buildmosaic.org, following the security policy. Do not open a public issue. The policy limits security updates to the latest minor release.