App Builder

This is a ready-to-go Offline First Compose Multiplatform starter kit built to help you spin up full-stack apps fast. It bundles a Compose Multiplatform frontend for Android, iOS, Desktop, and Web right alongside a built-in Ktor backend. Everything is pre-wired so you can skip the boilerplate and go straight to shipping for every platform from a single codebase.

Table of Contents

• Architecture
  • Supported Platforms
  • Platform Source Sets
  • Main Tech Stack
  • Modules
  • Package Responsibilities
  • Modules Structure
    • Shared
    • Design
    • Compose App
    • Server
  • Testing Strategy
  • UI
  • Dependency Management
  • Context Management
  • Feature Flags
  • Platform Specific Implementations
• Development Workflow
  • Environment Setup
  • Feature Creation
  • Testing
  • Deployment & Distribution

Architecture

Kotlin Multiplatform project following a Layered Clean Architecture designed around a Unidirectional Dependency Flow.

Supported Platforms

• Android
• iOS
• Windows
• macOS
• Linux
• Web

Platform Source Sets

Source Set	Platform
androidMain	Android API 26+
appleMain	iOS 16+ / macOS
desktopMain	JVM 21
webMain	WASM-JS
server	JVM 21

Main Tech Stack

• UI: Compose Multiplatform
• Client Database: SQLDelight
• Server Database Exposed
• Networking: Ktor
• Code Coverage: Kover

Modules

• shared: Code that is reused across all target platforms (Client and Server).
• design: Design System where all UI components live.
• composeApp: Client side for Android, iOS, Desktop, and Web.
• server: The backend for the application.

The packages across these modules obey the same structure.

Package Responsibilities

Each package has a specific isolated responsibility, and dependencies always point in a single direction down the stack.

• core: Business logic agnostic implementations. It is the foundation and cannot depend on any other layer.
• data: Responsible for data persistence and retrieval. Provides infrastructure for Network, Database and Storage. It can only depend on core.
• domain: Business workflows and rules. It can depend on data and core.
• ui: User-facing presentation layer. It can depend on domain, data and core.
• test: Test utilities like annotations and fake data shared across test source sets. It can depend on all layers, domain, data, core, ui.

Modules Structure

Shared

core

• flow: Coroutine dispatchers.
  • Dispatcher: Provides Main, Default and IO coroutine dispatchers as mutable properties so tests can substitute their own implementations.
• locale: Localization and date/time formatting.
  • DateTime: Utilities for getting the current time in UTC/ISO8601, epoch and duration calculation.
• platform: OS-specific APIs.
  • Platform: Provides a snapshot of the current execution environment with a sealed interface that defines the possible platforms that the application can run on.
• security: Cryptography and UUID utilities.
  • Uuid: UUID generation via the best available platform algorithm.
• telemetry: Logging and crash reporting.
  • Telemetry: Hub for dispatching telemetry data, including logs, error reports, and user feedback, by iterating over pluggable TelemetryEngine implementations.

data

• http: Ktor configuration and network logic.
  • Header: Sealed class of all header keys.
  • Query: Sealed class of all query parameter keys.
  • URL: Sealed class of all remote endpoints, serving as a centralized registry for API routing.
• serializer: JSON parsing and serialization.
  • Json: Helpers for encoding/decoding.

domain

Contains all the domain models.

test

Annotations used to exclude tests from coverage reports.

Design

data

• translation: Translation related tools.
  • TranslationCache: A cache dedicated to translations.

ui

• Color: Defines LocalColorScheme for light and dark themes.
• Typography: Defines LocalTypography for the text fonts.
• Shapes: Defines LocalShapes for the shape system.
• Translations: Composable helpers to read from TranslationCache. Provides LocalTranslationState.
• Theme: Main app theme definition that uses the previously described CompositionLocals.
• Preview: Wrapper composable that the application theme for accurate rendering in previews.
• core: UI core components like Text, Button, Image, etc. that provide the building blocks for composite components.
• component: UI composite components for specific features built upon the core components.

Compose App

core

• flag: Feature flags.
  • Flags: Data class with boolean controls for feature flags.
  • FeatureFlags: Exposes flags for runtime toggling.
• player: Media Player implementations.
  • AudioPlayer: Abstraction with a sealed Action interface (Play, Pause, Resume, Toggle). Manages playlist deduplication and shuffling and delegates platform-specific playback to subclasses.
• locale: Localization and date/time formatting.
  • Language: App default language and other language listings.
  • Locale: Methods to get the current system language, locale-aware datetime formatting, and a Flow that emits on locale changes.
• notification: Notification system implementation.
  • Notification: Platform specific implementation of a trigger of a native system notification defined by NotificationData.
  • NotificationPayload: Exposes a Flow used to bridge the Native OS notifications interactions with the common code.
• platform: OS-specific APIs.
  • Development: Development mode flag.
  • AppDataPath: Indicates the absolute path to the application's directory.
• security: Cryptography and UUID utilities.
  • Cryptography: Cryptography methods like encrypt/decrypt and hashing.
• telemetry: Logging and crash reporting.
  • PlatformLogger: A TelemetryEngine implementation for native system console outputs.
  • Console: An in-memory circular buffer for an in-app console feature.

data

• database: SQLDelight implementations, tables and drivers.
  • adapter: List of adapters used to marshal and map data types to and from a database.
  • DatabaseFactory: Creates the main AppDatabase with the adapters.
  • SqlDriver: Creates the database driver.
  • NoOpSqlDriver: A no-op implementation of SqlDriver.
  • Database: Database extension helpers.
• http: Ktor configuration and network logic.
  • plugin: Plugins used by the Ktor Http engine, like telemetry logging, timeouts, HTTP caching, encoding and JSON content negotiation.
  • HttpClientFactory: Creates a httpClient with the plugins.
  • HttpClientEngine: Creates the http client engine.
  • NoOpHttpClientEngine: A no-op implementation of HttpClientEngine. Returns 204 for every request.
  • Network: Network status helpers.
  • Http: Extensions to execute type-safe requests and decode the response into a HttpResult<Success|Error>.
• resource: Resource index.
  • AudioResource: Sealed class functioning as a resource index for audio in commonMain/resources/tracks.
  • ImageResource: Sealed class functioning as a resource index for images in commonMain/resources/drawable.
  • JsonResource: Sealed class functioning as a resource index for JSONs in commonMain/composeResources/files.
  • ResourceLoader: Loads resources via the Compose Resources API.
• storage: File system access.
  • File: Declarations for suspending save/load/delete file operations.
  • Storage: Implements StorageFile interface to manage the state and persistence of key-value files. Uses a Mutex-protected I/O to prevent race conditions and a read-only stream as an in-memory cache for faster fetch operations.
  • StorageKey: Sealed class of keys used in StorageFile implementations.
• device: Device specific code.
  • Device: Generates and fetches a device installation uuid.

domain

• translation: Translation service.
  • TranslationService: Service to monitor locale and translations.
• notification: Notification service.
  • NotificationService: Notifications service that listens for user notifications.
• scheduler: Scheduler implementation.
  • Job: A persistent background execution unit handled by the scheduling subsystem.
  • JobFactory: Translates Jobs into executable runtime actions and is implemented by JobProvider.
  • Scheduler: Orchestrates dispatch logic by managing job queues destined for persistent execution and is implemented by JobScheduler.
  • JobResult: Represents the final outcome of a Job.
• usecase: Implementation of specific business workflows. Each use case is a sub-package containing the interface and its gateway implementation.
  • Gateways: Aggregates all gateways under the UseCases file.

ui

• App: Main composable that assembles the application UI and acts as the top-level container for the user-facing elements.
• lifecycle: Platform-aware lifecycle observers.
  • Lifecycle: Composable that registers foreground/background callbacks, with an optional recomposition key.
• player: Media Player composables.
  • AudioPlayer: Composable that manages audio playback respecting the app lifecycle.
• navigation: Routing logic.
  • provider: Definitions of the navigation routes.
  • scene: Scene strategies used to render a list of entries.
  • Screen: Sealed interface that enumerates all destinations.
  • Router: Handles routing logic and manages the navigation backstack. It is implemented by Navigator.
  • NoOpRouter: A no-op implementation of Router.
  • Navigation: Composable that sets up the navigation and defines all the possible navigation destinations within the app.
  • Routing: Navigation utility functions.
• component: UI components implementations. Each component is a sub-package containing the composable and respective store for state management, all co-located.
  • Store: ViewModel with a StateFlow<State> as the single source of truth for the UI and reducer override to process actions from the UI.
• screen: These are the UI entry points built with components. Each screen is also sub-package containing the composable and respective store for state management, all co-located.
  • Screen: Wrapper composable that provides the foundational UI.

root level

• Dependency: Manual dependency injection. This class wires everything together. It initializes the full stack: SqlDriver → AppDatabase, HttpClientEngine → HttpClient, to be used by the Scheduler and UseCases via Gateways.
• Application: Entry point of the application. It initializes the Dependency graph, telemetry, feature flags, user observer and services. Provides dependency Flows that modules can observe to ensure initialization is complete before interacting with dependencies.

Server

core

• platform: OS-specific APIs.
  • Env: Environment variables definitions.
  • Property: Property definitions.
• security: Cryptography and UUID utilities.
  • Cryptography: Cryptography methods to hash and verify passwords.
  • TicketManager: Manages single-use, short-lived tickets for connections.
• telemetry: Logging and crash reporting.
  • ServerLogger: A TelemetryEngine implementation for server outputs.

data

• database: Exposed implementations, tables and drivers.
  • DatabaseFactory: Creates a R2dbcDatabase.
  • Database: Database extension helpers.
• http: Ktor configuration and network logic.
  • plugin: Plugins used by the Ktor Http engine.

domain

• route: Defines the routing endpoints for the server.
• usecase: Implementation of specific business workflows. Each use case is a sub-package containing the interface and its gateway implementation.
  • Gateways: Aggregates all gateways under the UseCases file.

test

Fake data and demo accounts setup.

root level

• Application: Entry point of the server application. Initializes the telemetry logger and starts the server.

Development Workflow

Environment Setup

By default, signing keys and some envs are read from a local.properties file in the root directory. Change this method at your leisure.

• Android Signing: android.storeFile, android.keyAlias, android.keyPassword, android.storePassword.
• Mac Notarization: mac.sign.identity, mac.notarization.appleId, mac.notarization.teamId, mac.notarization.password.
• Sentry Monitoring: sentryDsn for production monitoring.
• Environment Variables: server.port, server.jwt.issuer, server.jwt.audience, server.jwt.secret

Feature Creation

New features should be gated behind a flag in Flags.kt. FeatureFlags exposes flags for runtime toggling. Below are the steps to create a new isolated feature.

Shared Module

1. Domain: Add the domain file(s) in the domain package.

Design Module

1. UI Components: Add the needed components.

Client Module

1. Flag: Add in Flags.kt the feature: val {feature}: Boolean and set it to false on FeatureFlags and true on Application.
2. Components with Store: Create a new package ui/component/{component} with files {Component}, {Component}StateAction, {Component}Store.
3. Screen: Create a new package ui/screen/{feature} with files {Feature}Screen, {Feature}StateAction, {Feature}Store.
4. UseCase: Create the use cases in domain/usecase and the needed .sq files in the folder sqldelight.
5. Scheduler: Create the needed jobs in domain/scheduler/JobProvider for offline capabilities.
6. Navigation: Add to the ui/navigation package the new screen in the sealed class Screen, the new route in the provider package and the link it in the composable navigation in Navigation, gated by the feature flag.

Server Module

1. Flag: Add in Flags.kt the feature: val {feature}: Boolean and set it to false on FeatureFlags and true on Gradle Envs configuration.
2. Database: Add the feature entity to data/database and the table creation in DatabaseFactory.
3. UseCase: Create the use cases in domain/usecase.
4. Route: Add the feature routes in domain/route in the provider package and the link it in the Routing file, gated by the feature flag.

UI Specifics

Compose screens use a custom MVI Store pattern. Each screen has a Store ({Screen}Store) and a Screen composable ({Screen}Screen). Jobs inside a Store can be launched with an ID to cancel/replace prior work. The UI state uses kotlinx.collections.immutable (ImmutableList, ImmutableSet) to prevent accidental mutations.

Store<State, Action> (extends ViewModel) is the base class:

• stateFlow: StateFlow<State> — single source of truth observed by the composable
• send(action) → reducer(state, action) — the only entry point for UI events
• updateState { } — the only way to mutate state
• launch(id, replace, context) { } — launches a coroutine tied to an ID
• Flow<T>.observe(id) { } — lifecycle-aware collection that pauses after the UI unbinds and resumes when it reattaches

Context Management

On Android, use the applicationContext provided via KInitializer to avoid explicit context injection.

Testing

The testing structure mirrors the source code to ensure 1:1 coverage.

Client Module

Coverage excludes @Serializable classes, @Preview composables, and anything annotated with @ExcludeFromTesting. Write tests in commonTest whenever possible. Platform-specific test setup lives in the PlatformTestCase expect/actual classes.

• Unit/UI Tests: Should run in the commonTest source set whenever possible. Use the TestCase harness for hermetic Unit/UI testing with mock engines.
• Coverage: Kover is configured to verify a minimum of 90% code coverage.
• Command: Run all tests using ./gradlew clean testAllAndReport.

All client tests extend TestCase, which provides a hermetic environment:

• dependency — Dependency with an in-memory SQLDelight driver and a mock Ktor engine
• runUnitTest { } — Sets up the test environment, resets all data, runs unit test then tears down
• runUITest { } — Same thing but for UI test. Use setUI { } to render composables under AppTheme with mock lifecycle and navigation

Server Module

WIP

Platform Specific Implementations

WIP

Deployment & Distribution

Bump versions in the files:

• build.gradle.kts
• info.plist
• project.pbxproj

Standard compile commands for different platforms include:

• iOS: Xcode archive
• Android: ./gradlew clean bundleRelease
• Mac: ./gradlew clean notarizeDmg --no-configuration-cache
• Windows: ./gradlew clean packageMsi
• Linux: ./gradlew clean packageDeb
• Web: ./gradlew clean deployWeb
• Server: ../gradlew :server:buildFatJar