miru-sdk

0.1.9indexed

Modular, configurable SDK accelerating mobile app development with clean-architecture modules, type-safe networking, state management, navigation, Material UI components, DI, Firebase, social auth, persistence.

AndroidNative·wahidabd/miru-sdk

Stars

—

Used by

dependents

—

Health

/ 100

Miru SDK

Kotlin Multiplatform SDK for accelerating mobile development.

Miru SDK provides a modular, configurable foundation for building Android and iOS apps with shared business logic and UI components. Designed as an internal base project for software houses, it handles networking, state management, navigation, theming, and dependency injection out of the box — so your team can focus on features, not boilerplate.

Each module follows Clean Architecture principles with clear separation into data, domain, and presentation layers, ensuring testability, maintainability, and independence between layers.

Read the full documentation →

Features

Architecture

Clean Architecture Per Module

Each module in Miru SDK is internally structured following Clean Architecture with three layers:

┌──────────────────────────────────────────────┐
│              Presentation Layer               │
│  (UI Composables, ViewModels, UiState)        │
│                     │                         │
│                     ▼                         │
│               Domain Layer                    │
│  (Use Cases, Repository Interfaces, Models)   │
│                     │                         │
│                     ▼                         │
│                Data Layer                     │
│  (Repository Impl, API, DAO, DataSource)      │
└──────────────────────────────────────────────┘

Domain is the innermost layer with zero dependencies — it defines interfaces (repository contracts) and business models. Data implements those interfaces with concrete data sources (API, Room, DataStore). Presentation consumes domain use cases/repositories and exposes UI state.

The dependency rule flows inward only: presentation → domain ← data. The data layer depends on domain (to implement interfaces), but domain never depends on data or presentation.

Module Dependency Graph

graph TD
    APP[Your App] --> SDK[":miru-sdk"]

    SDK --> DI[":di"]
    SDK --> UI[":ui-components"]
    SDK --> STATE[":ui-state"]
    SDK --> NAV[":navigation"]
    SDK --> FB[":firebase"]
    SDK --> AUTH[":auth"]
    SDK --> PERSIST[":persistent"]

    DI --> NETWORK[":network"]
    DI --> CORE[":core"]
    AUTH --> CORE
    PERSIST --> CORE
    FB --> CORE
    UI --> CORE
    STATE --> CORE
    NAV --> CORE
    NETWORK --> CORE

    style APP fill:#4CAF50,color:#fff,stroke:none,rx:8
    style SDK fill:#00BCD4,color:#fff,stroke:none,rx:8
    style DI fill:#FF9800,color:#fff,stroke:none,rx:8
    style AUTH fill:#E91E63,color:#fff,stroke:none,rx:8
    style FB fill:#FF5722,color:#fff,stroke:none,rx:8
    style UI fill:#2196F3,color:#fff,stroke:none,rx:8
    style STATE fill:#2196F3,color:#fff,stroke:none,rx:8
    style NAV fill:#2196F3,color:#fff,stroke:none,rx:8
    style PERSIST fill:#795548,color:#fff,stroke:none,rx:8
    style NETWORK fill:#9C27B0,color:#fff,stroke:none,rx:8
    style CORE fill:#607D8B,color:#fff,stroke:none,rx:8

Internal Module Layer Structure

Each feature module follows this pattern internally:

:feature-module/
└── src/commonMain/kotlin/
    └── com/miru/sdk/feature/
        ├── data/                  # Data Layer
        │   ├── repository/        #   Repository implementations
        │   ├── source/            #   Remote/Local data sources
        │   ├── model/             #   DTOs, entities, API models
        │   └── mapper/            #   Data ↔ Domain mappers
        ├── domain/                # Domain Layer
        │   ├── repository/        
        │   ├── model/             
        │   └── usecase/           
        └── presentation/          
            ├── ui/                
            └── viewmodel/

Not all modules have all three layers. Foundation modules like :core and :network primarily provide domain and data layer abstractions. UI-only modules like :ui-components are purely presentation.

Data Flow (Clean Architecture)

sequenceDiagram
    participant UI as Composable (Presentation)
    participant VM as ViewModel (Presentation)
    participant UC as UseCase (Domain)
    participant REPO as Repository (Domain Interface)
    participant IMPL as RepositoryImpl (Data)
    participant API as ApiService / DAO (Data)

    UI->>VM: User action
    VM->>UC: execute()
    UC->>REPO: getUsers()
    REPO->>IMPL: (injected impl)
    IMPL->>API: Ktor request / Room query
    API-->>IMPL: Response / Exception
    IMPL-->>IMPL: Map DTO → Domain Model
    IMPL-->>UC: Resource<DomainModel>
    UC-->>VM: Resource<DomainModel>
    VM->>VM: setState { ... }
    VM-->>UI: StateFlow emission
    UI->>UI: Recompose

Modules

Tech Stack

Installation

Miru SDK is available on Maven Central — no extra repository configuration needed.

Kotlin Multiplatform

kotlin {
    sourceSets {
        commonMain.dependencies {
            // All-in-one — includes core, network, ui-state, navigation,
            // ui-components, di, firebase, auth, and persistent
            implementation("io.github.wahidabd:miru-sdk:<version>")
        }

        // Or pick only what you need
        // commonMain.dependencies {
        //     implementation("io.github.wahidabd:miru-sdk-core:<version>")
        //     implementation("io.github.wahidabd:miru-sdk-network:<version>")
        //     implementation("io.github.wahidabd:miru-sdk-ui-state:<version>")
        // }
    }
}

Android Only

dependencies {
    implementation("io.github.wahidabd:miru-sdk:<version>")
}

Replace <version> with the latest release from Maven Central.

Quick Start

1. Initialize the SDK

// Application.kt or shared entry point
MiruSdkInitializer.initialize(
    MiruSdkConfig(
        networkConfig = NetworkConfig(
            baseUrl = "https://api.yourapp.com/v1/",
            enableLogging = BuildConfig.DEBUG
        ),
        enableLogging = true,
        tokenProvider = MyTokenProvider(),     // optional
        additionalModules = listOf(appModule) // your Koin modules
    )
)

2. Define Domain Layer (models, repository interface, use case)

3. Implement Data Layer (API, DTO, mapper, repository impl)

4. Create Presentation Layer (ViewModel + UI)

5. Wire Dependencies (Koin Module)

// di/UserModule.kt — bind all layers via Koin
val userModule = module {
    // Data
    single { UserMapper() }
    single { UserApi(get()) }
    single<UserRepository> { UserRepositoryImpl(get(), get()) }

    // Domain
    factory { GetUsersUseCase(get()) }

    // Presentation
    viewModel { UserListViewModel(get()) }
}

6. Set Up Navigation

@Composable
fun AppNavigation() {
    val navigationManager = remember { NavigationManagerImpl() }

    MiruNavigationHost(startDestination = "home") {
        composable("home") { HomeScreen() }
        composable("users") { UserListScreen() }
        composable("user/{id}") { backStackEntry ->
            val id = backStackEntry.getIntArgument("id")
            UserDetailScreen(userId = id)
        }
    }
}

Module Details

Core

The foundation layer with zero UI dependencies.

Resource wraps all async operations:

val result: Resource<User> = userApi.getUserById(1)

result
    .onSuccess { user -> println(user.name) }
    .onError { exception, _ -> println(exception.message) }
    .onLoading { println("Loading...") }

AppException provides typed error handling:

when (exception) {
    is AppException.UnauthorizedException -> navigateToLogin()
    is AppException.NetworkException -> showOfflineMessage()
    is AppException.ServerException -> showServerError(exception.code)
    is AppException.TimeoutException -> showRetryDialog()
    else -> showGenericError()
}

Extensions for common operations:

// String
"hello world".capitalizeFirst()   // "Hello world"
"test@email.com".isValidEmail()   // true

// Flow
flow.throttleFirst(300L)
flow.retryWithExponentialBackoff(maxRetries = 3)
flow.asResource() // Flow<T> -> Flow<Resource<T>>

// Collections
list.safeGet(99)                    // null instead of crash
list.updateIf({ it.id == 5 }) { it.copy(name = "Updated") }

Network

The network module provides data layer abstractions for HTTP communication.

Domain layer — TokenProvider interface (repository contract for auth tokens):

Data layer — ApiService as base remote data source, safeApiCall for error mapping:

// Your API extends ApiService (data/source layer)
class ProductApi(httpClient: HttpClient) : ApiService(httpClient) {
    suspend fun getProducts(): Resource<ApiResponse<List<ProductDto>>> = get("products")
}

Token events — observe globally for auth state changes:

TokenEventBus.events.collect { event ->
    when (event) {
        TokenEvent.ForceLogout -> navigateToLogin()
        TokenEvent.TokenExpired -> refreshToken()
        TokenEvent.TokenRefreshed -> retryRequest()
    }
}

UI State

The ui-state module provides presentation layer base classes.

BaseViewModel provides five helpers for handling async operations, from simplest to most flexible:

collectResource() — zero boilerplate, pipes a one-shot suspend → Resource<T> straight into a MutableStateFlow:

class SpotlightViewModel(
    private val useCase: GetSpotlightUseCase
) : BaseViewModel<Unit, SpotlightEvent>(Unit) {

    private val _spotlight = MutableStateFlow<Resource<List<Spotlight>>>(Resource.Loading())
    val spotlight = _spotlight.asStateFlow()

    fun load() = collectResource(_spotlight) { useCase.spotlight() }
}

collectFlow() — plain Flow<T> auto-wrapped into Resource, piped to a MutableStateFlow:

class NotificationViewModel(
    private val observeNotifications: ObserveNotificationsUseCase
) : BaseViewModel<Unit, NotificationEvent>(Unit) {

    private val _notifications = MutableStateFlow<Resource<List<Notification>>>(Resource.Loading())
    val notifications = _notifications.asStateFlow()

    fun observe() = collectFlow(_notifications, distinctUntilChanged = true) {
        observeNotifications() 
    }
}

collectFlowResource() — Flow<Resource<T>> piped directly to a MutableStateFlow:

class LiveFeedViewModel(
    private val observeLiveFeed: ObserveLiveFeedUseCase
) : BaseViewModel<Unit, LiveFeedEvent>(Unit) {

    private val _feed = MutableStateFlow<Resource<List<FeedItem>>>(Resource.Loading())
    val feed = _feed.asStateFlow()

    fun observe() = collectFlowResource(_feed) {
        observeLiveFeed() // returns Flow<Resource<List<FeedItem>>>
    }
}

execute() — one-shot suspend calls with state reducers:

class ProductViewModel(
    private val getProductsUseCase: GetProductsUseCase
) : BaseViewModel<ProductState, ProductEvent>(ProductState()) {

    fun loadProducts() = execute(
        call = { getProductsUseCase() },
        onLoading = { copy(isLoading = true) },
        onSuccess = { copy(products = it, isLoading = false) },
        onError = { copy(error = it.message, isLoading = false) }
    )
}

collect() — reactive streams (Flow<Resource<T>>) with state reducers:

class BookmarkViewModel(
    private val observeBookmarksUseCase: ObserveBookmarksUseCase
) : BaseViewModel<BookmarkState, BookmarkEvent>(BookmarkState()) {

    fun observe() = collect(
        flow = { observeBookmarksUseCase() },
        distinctUntilChanged = true,
        onLoading = { copy(isLoading = true) },
        onSuccess = { copy(bookmarks = it, isLoading = false) },
        onError = { copy(error = it.message, isLoading = false) }
    )
}

PagingState for list pagination:

data class FeedState(
    val paging: PagingState<Post> = PagingState()  // Post = domain model
)

// Append new page
setState { copy(paging = paging.appendItems(newPosts)) }

// Refresh
setState { copy(paging = paging.refresh(freshPosts)) }

UI Components

Theming — customize per project:

MiruTheme(
    colorScheme = MiruColorScheme(
        primary = Color(0xFF1E88E5),
        secondary = Color(0xFFFF6F00),
        // ... your brand colors
    ),
    typography = MiruTypography(
        titleLarge = TextStyle(fontSize = 22.sp, fontWeight = FontWeight.Bold),
        // ... your typography
    )
) {
    // All Miru components inherit these values
    MiruButton(text = "Submit", onClick = { })
}

Available components:

MiruButton          MiruTextField       MiruPasswordField
MiruSearchField     MiruTopBar          MiruSearchTopBar
MiruBottomSheet     MiruCard            MiruInfoCard
MiruAlertDialog     MiruLoadingDialog   MiruConfirmationDialog
MiruErrorView       MiruEmptyView       MiruFullScreenLoading
MiruLoadingIndicator MiruShimmerEffect  MiruNetworkImage
MiruResourceView    MiruSpacer          MiruVerticalSpacer
MiruHorizontalSpacer

MiruResourceView — eliminates repetitive when (resource) boilerplate in screens. Works with any StateFlow<Resource<T>> regardless of which helper populated it (collectResource, collectFlow, collectFlowResource, execute, or collect):

@Composable
fun SpotlightScreen(viewModel: SpotlightViewModel = koinViewModel()) {
    val spotlightResource by viewModel.spotlight.collectAsStateWithLifecycle()

    MiruResourceView(
        resource = spotlightResource,
        loadingMessage = "Loading spotlight...",
        onRetry = { viewModel.load() }
    ) { items ->
        LazyColumn {
            items(items, key = { it.id }) { item ->
                SpotlightCard(item)
            }
        }
    }
}

You can also customize the loading and error states:

MiruResourceView(
    resource = feedResource,
    onRetry = { viewModel.refresh() },
    onLoading = { MyCustomShimmer() },
    onError = { message -> MyCustomErrorBanner(message) }
) { data ->
    FeedContent(data)
}

Firebase

Remote Config — fetch and read config values:

val config: MiruRemoteConfig = get() // via Koin

// Set defaults before fetching
config.setDefaults(mapOf(
    "feature_new_ui" to false,
     to ,
     to 
))


config.fetchAndActivate().collect { resource ->
    resource.onSuccess { activated -> println() }
}


 featureEnabled = config.getBoolean()
 apiUrl = config.getString()
 maxRetry = config.getLong()

FCM Topic Management — subscribe/unsubscribe with reactive state tracking:

val topicManager: TopicManager = get() // via Koin

// Subscribe to topics
topicManager.subscribe("promo")
topicManager.subscribeAll(listOf("news", "updates", "alerts"))

// Observe active subscriptions reactively
topicManager.subscribedTopics.collect { topics ->
    println("Subscribed to: $topics")
}

// Check & unsubscribe
if (topicManager.isSubscribed("promo")) {
    topicManager.unsubscribe()
}

Koin setup:

startKoin {
    modules(
        firebaseModule, // provides MiruRemoteConfig, MiruMessaging, TopicManager
        // ... other modules
    )
}

Auth

Google Sign-In — standalone One Tap, dapet idToken langsung (no Firebase):

// 1. Initialize once at app startup
MiruGoogleAuth.initialize(serverClientId = "YOUR_SERVER_CLIENT_ID")

// 2. Pre-built Compose button
MiruGoogleSignInButton { resource ->
    resource.onSuccess { auth ->
        // Send idToken to your backend API
        api.loginWithGoogle(auth.idToken!!)
    }
}

Apple Sign-In — native iOS only, returns identityToken:

val appleAuth: MiruAppleAuth = get()

if (appleAuth.isAvailable()) {
    val result = appleAuth.signIn() // shows native Apple popup
    result?.let { auth ->
        // auth.idToken = Apple identityToken
        // auth.email, auth.displayName
        api.loginWithApple(auth.idToken!!)
    }
}

Facebook Login — native SDK, returns accessToken:

// Android: set ActivityResultRegistryOwner before sign-in (in your Activity's onCreate)
MiruFacebookAuth.setActivityResultRegistryOwner(this)

val facebookAuth: MiruFacebookAuth = get()

val result = facebookAuth.signIn() // shows Facebook login popup
result?.let { auth ->
    // auth.accessToken = Facebook access token
    // auth.email, auth.displayName, auth.photoUrl
    api.loginWithFacebook(auth.accessToken!!)
}

// Android: clear in onDestroy to prevent leaks
MiruFacebookAuth.clearActivityResultRegistryOwner()

MiruAuthManager — centralized auth state (provider-agnostic):

val authManager: MiruAuthManager = get()

// Observe auth state reactively
authManager.currentUser.collect { user ->
    if (user != null) navigateToHome()
    else navigateToLogin()
}

// Handle any sign-in result
MiruGoogleSignInButton { resource ->
    authManager.handleSignInResult(resource)
}

// Sign out
authManager.signOut()

Provider	Platform	Implementation
Google

HTTP Inspector (Chucker)

Chucker is automatically activated on Android debug builds with zero consumer configuration. Every HTTP request made through the SDK's HttpClient is captured and accessible via a notification in the status bar.

Consumer app setup — add Chucker to your app's build.gradle.kts:

dependencies {
    debugImplementation("com.github.chuckerteam.chucker:library:4.3.1")
    releaseImplementation("com.github.chuckerteam.chucker:library-no-op:4.3.1")
}

That's it — no initialization code needed. The SDK's PlatformModule picks up ChuckerInterceptor via Koin and injects it into OkHttp automatically. In release builds, the no-op variant is used so there is zero overhead.

Chucker is Android-only. iOS builds compile and run normally — the interceptor list is simply empty on that platform.

Persistent

The :persistent module provides local storage through Room KMP (SQLite database) and DataStore (key-value preferences).

Setup — initialize in your Application.onCreate() (Android):

MiruPreferencesInitializer.init(applicationContext)
MiruDatabaseInitializer.init(applicationContext)

DataStore Preferences — MiruPreferences wraps DataStore with a convenient API:

val prefs: MiruPreferences = get() // via Koin

// Write
prefs.putString("user_name", "Wahid")
prefs.putBoolean("dark_mode", true)
prefs.putInt("login_count", )


 name = prefs.getString(, )


prefs.observeBoolean(, ).collect { isDark ->
    
}


prefs.remove()
prefs.clear()

Room KMP Database — define your database in commonMain, build with miruBuild():

Component	Description

Project Structure

Each module follows the clean architecture layer convention where applicable. The layers are annotated with [domain], [data], and [presentation] labels.

Layer Mapping Summary

Sample App

The :sample module is a fully functional News Reader app built with Miru SDK, demonstrating clean architecture, real API integration, and multiplatform support (Android + iOS).

Features

The sample app uses NewsAPI.org to fetch real headlines and articles, with BottomNavigation containing four tabs: Home (browse by category), Search (full-text search), Bookmarks (local Room database), and Settings (dark mode toggle, font size adjustment). Article detail screens are accessible from any tab.

Running the Sample

Android — open in Android Studio and run the :sample:app module. The API key is read from sample/env.properties:

# sample/env.properties (git-ignored)
NEWS_API_KEY=your_api_key_here

Copy sample/env.properties.example and fill in your key from newsapi.org. On a debug build, Chucker is active — tap the notification to inspect all HTTP requests made by the app.

iOS — open sample/iosApp/iosApp.xcodeproj in Xcode. The API key is configured in sample/iosApp/Config.xcconfig. Build and run on a simulator or device — the Kotlin framework compiles automatically via a Gradle build phase.

Architecture

The sample follows the same layered architecture as the SDK: DTOs and API client in the data layer, mappers converting to domain models, a repository with in-memory caching, and ViewModels exposing UiState flows consumed by Compose screens. Koin provides dependency injection across both platforms.

Requirements

Kotlin 2.4.0+
Compose Multiplatform 1.11.1+
Android: minSdk 24, compileSdk 37
iOS: iosArm64, iosSimulatorArm64 (Apple Silicon)
Gradle 9.1+
JDK 21+

License

Related libraries

Surfaced from shared tags and platforms — no rankings paid for.

charty★ 1.3k

hi-manshuLightweight charting toolkit delivering sleek, customizable charts with a minimal API, performant rendering, easy theming, and concise documentation for rapid UI integration.Shared: compose-multiplatform, cmp

Camposer★ 296

ujizinMultifeature camera UI library for capturing photos and videos with zoom, tap-to-focus, flash/torch, exposure control, multi-lens support, 30/60 FPS recording, stabilization, and code scanning.Shared: compose-multiplatform, cmp

mediamp★ 112

open-aniMedia player wrapper offers unified abstraction over popular libraries like ExoPlayer and VLC, supporting backend-specific features and advanced use cases, including playback speed adjustments and custom media data handling.Shared: compose-multiplatform, cmp

gadulka★ 73

kkostovMinimalistic audio player library enabling audio playback without UI, wrapping native functionality in "headless" mode. Compatible with various platforms and includes examples for Jetpack Compose integration.Shared: compose-multiplatform, cmp

validable★ 72

devscastExtensible library simplifies text field validation, offering abstraction and reusable logic for UI frameworks. Features include error handling and validation state management. No longer maintained.Shared: compose-multiplatform, cmp

fastscroller-compose-multiplatform★ 51

oikvpqyaEnhances scroll bar functionality across various platforms, inspired by Google's Launcher3 FastScroller. Includes customizable styles and optional Material Design themes for seamless integration.Shared: compose-multiplatform, cmp

`:miru-sdk`	Umbrella module — single dependency that re-exports all modules below via `api()`
`:core`	Base utilities — `Resource<T>`, `AppException`, `Mapper`, extensions, logging
`:network`	HTTP client — `ApiService`, `safeApiCall`, token management, error handling
`:ui-state`	State management — `BaseViewModel`, `UiState`, `MutableEventFlow`, pagination
`:navigation`	Navigation — `NavigationManager`, safe navigation, transitions, result passing
`:ui-components`	UI library — Buttons, TextFields, Dialogs, TopBar, BottomSheet, Theming
`:firebase`	Firebase KMP — Remote Config, FCM topic subscribe/unsubscribe, TopicManager
`:auth`	Social Auth — Google, Apple, Facebook OAuth with pre-built Compose sign-in buttons
`:persistent`	Local storage — Room KMP database + DataStore preferences with convenient wrappers
`:di`	DI & init — `MiruSdkInitializer`, Koin modules, Compose injection helpers

Kotlin	2.4.0	Language
Compose Multiplatform	1.11.1	Shared UI
Ktor	3.5.1	HTTP Client
Koin	4.2.2	Dependency Injection
Kotlinx Serialization	1.11.0	JSON parsing
Kotlinx Coroutines	1.11.0	Async programming
Firebase KMP (GitLive)	2.4.0	Remote Config, FCM
KMPAuth	2.5.0-alpha01	Google, Apple, Facebook OAuth
Room KMP	2.8.4	Local database
DataStore KMP	1.2.1	Preferences storage
Coil	3.5.0	Image loading
Napier	2.7.1	Multiplatform logging
Chucker	4.3.1	Android HTTP inspector (debug)
AGP	9.2.1	Android build

`MiruPreferences`	DataStore wrapper with type-safe get/put/observe for String, Int, Long, Float, Double, Boolean
`MiruDatabase`	Room builder helper with pre-configured BundledSQLiteDriver + Dispatchers.IO
`databasePath()`	Platform-specific database file path resolver
`persistentModule`	Koin module providing MiruPreferences

`:core`	Resource, AppException, Mapper, Extensions	Logger, DispatcherProvider	—
`:network`	TokenProvider, TokenEvent	ApiService, SafeApiCall, HttpClient, DTOs	—
`:ui-state`	—	—	BaseViewModel, UiState, EventFlow, PagingState
`:navigation`	NavigationManager, NavigationResult	—	MiruNavHost, Transitions
`:ui-components`	—	—	Theme, Buttons, Cards, Dialogs, etc.
`:auth`	AuthResult, MiruAuthManager	Google/Apple/Facebook Auth impls	Sign-in buttons
`:firebase`	RemoteConfig/Messaging interfaces	Firebase impl, TopicManager	—
`:persistent`	Preferences/Database interfaces	Room, DataStore, platform paths	—
`:di`	—	Koin module wiring	—