KeystoneKMP

A feature-first Kotlin Multiplatform (KMP) architecture boilerplate for building scalable, maintainable mobile applications with shared business logic and flexible UI strategies.

KeystoneKMP is designed around:

• Feature isolation
• Replaceable infrastructure
• Predictable navigation
• Shared domain logic
• Clean dependency boundaries

This repository is a boilerplate, not a framework. It provides architectural structure and conventions that can be reused across multiple applications.

---

✨ Key Principles

• Share business logic across platforms
• Prefer shared UI when possible
• Allow platform-specific UI when required
• Keep features independent and self-contained
• Make infrastructure replaceable
• Drive UI through state, not navigation calls

Features define intent.
Apps handle mechanics.
Infrastructure remains replaceable.

---

📌 High level Diagram

                  ┌──────────────────────────┐
                  │        composeApp        │
                  │  (Android App Shell)     │
                  │                          │
                  │  - Navigation Impl       │
                  │  - DI Composition Root   │
                  │  - Feature Entry Wiring  │
                  └────────────┬─────────────┘
                               │
                               │
                  ┌────────────▼─────────────┐
                  │         iosApp           │
                  │   (iOS App Shell)        │
                  │                          │
                  │  - Native Navigation     │
                  │  - DI Composition        │
                  │  - Feature Entry Wiring  │
                  └────────────┬─────────────┘
                               │
                               │
    ┌──────────────────────────▼──────────────────────────┐
    │                     Feature Modules                 │
    │                                                     │
    │   ┌────────────────┐   ┌────────────────┐           │
    │   │  featureLogin  │   │  featurePayment│  ...      │
    │   │                │   │                │           │
    │   │  - Entry API   │   │  - Entry API   │           │
    │   │  - State       │   │  - State       │           │
    │   │  - ViewModel   │   │  - ViewModel   │           │
    │   │  - UI Flow     │   │  - UI Flow     │           │
    │   └───────┬────────┘   └───────┬────────┘           │
    │           │                    │                    │
    └───────────┼────────────────────┼────────────────────┘
                │                    │
                │                    │
    ┌───────────▼────────────────────▼─────────────────────┐
    │              Shared Infrastructure Modules           │
    │                                                      │
    │   ┌──────────┐  ┌──────────┐  ┌──────────┐           │
    │   │ Analytics│  │  Logger  │  │ Network  │           │
    │   └──────────┘  └──────────┘  └──────────┘           │
    │                                                      │
    │   ┌──────────────┐  ┌────────────────┐               │
    │   │ designSystem │  │  localStorage  │               │
    │   └──────────────┘  └────────────────┘               │
    │                                                      │
    │  (Provided by App via DI, consumed by Features)      │
    └──────────────────────────────────────────────────────┘

---

📁 Project Structure

.
├── composeApp        # Android application shell
├── iosApp            # iOS application shell (Xcode project)
│
├── featureLogin      # Example feature module
│
├── analytics         # Analytics abstraction layer
├── designSystem      # Shared design tokens & UI components
├── logger            # Logging abstraction
├── network           # Networking abstractions & clients
├── localStorage      # Persistent storage abstractions
│
└── build / gradle    # Build logic & tooling

---

📱 App Modules

composeApp

Android application shell responsible for:

• Application entry point
• Navigation implementation (e.g., Navigation 3)
• Dependency Injection composition root
• Wiring feature entry definitions

Rules:

• ❌ No business logic
• ❌ No feature internals
• ✅ Owns infrastructure lifetimes

---

iosApp

iOS application shell responsible for:

• SwiftUI / UIKit UI
• iOS navigation & lifecycle
• Dependency wiring
• Feature entry composition

---

🧩 Feature Modules

Each feature is fully self-contained and owns:

• Business rules
• State & screen flow
• Feature entry point
• Platform-specific UI when necessary

Typical internal structure:

featureLogin
├── api        # Public contracts (FeatureEntry, Navigator interfaces)
├── shared     # KMP business logic & state
├── android    # Compose UI + Android adapters
└── ios        # SwiftUI / UIKit + iOS adapters

Feature Rules

• Features do not depend on other feature implementations
• Features expose capabilities, not screens
• Features do not directly use navigation libraries
• Internal screen transitions are driven by state

---

🎨 UI Strategy

The preferred approach is to share UI across platforms when feasible.
However, when platform-specific behavior, performance, or UX differences require it, native UI implementations can be used per platform.

This flexibility allows:

• Faster development with shared UI where appropriate
• Native UX fidelity when platform nuances matter
• Incremental migration between shared and platform-specific UI

---

🔌 Shared Infrastructure Modules

These modules are reused across all features and provided by the app via dependency injection.

analytics

Provides analytics interfaces.
The app decides the actual analytics backend implementation.

designSystem

Shared UI tokens and reusable components:

• Colors, typography, spacing
• Reusable composables / SwiftUI views

Rules:

• ❌ No feature-specific screens
• ❌ No navigation logic
• ✅ Stateless UI components only

logger

Logging abstraction layer.
Features log through the interface; the app provides the concrete implementation.

network

Defines network client abstractions and factories.
A singleton instance is created and provided by the app using DI.

localStorage

Key-value storage and caching abstractions with platform-specific implementations.

---

🧭 Navigation Model

Navigation is intentionally split into two layers.

App-Level Navigation

Handles:

• Entering and exiting features
• Deep links
• Back stack management

Owned by:

• composeApp
• iosApp

---

Feature-Internal Navigation

Handled using state-driven UI instead of route-based navigation.

Example:

when (state.step) {
    Step.Form -> FormScreen()
    Step.Otp -> OtpScreen()
    Step.Success -> SuccessScreen()
}

This keeps feature flows encapsulated and testable without exposing internal screens to the app.

---

🧪 ViewModel & State Management

Each feature follows:

• One primary state owner (ViewModel)
• StateFlow as the source of truth
• UI emits events
• State determines which screen is rendered

Rules:

• No shared base ViewModel
• No navigation logic inside features
• Business logic stays inside feature layer

---

🔧 Dependency Injection

Koin is used for dependency injection.

Pattern:

• Features declare dependencies
• App provides singleton instances (network, logger, etc.)
• App loads all modules at startup

Rules:

• ❌ Features never create global singletons
• ❌ UI never wires dependencies manually
• ✅ App controls lifetimes and scopes

---

🚀 Why “Keystone”?

A keystone is the central stone that holds an arch together.

This architecture keeps:

• Features independent
• Infrastructure replaceable
• The system stable as it scales

---

❌ Non-Goals

This project does not aim to:

• Force fully shared UI across platforms
• Enforce a specific navigation library
• Provide a rigid framework or SDK
• Hide complexity behind heavy abstractions

---

🧭 Guiding Philosophy

Share what makes sense.
Specialize when necessary.
Isolate features.
Keep infrastructure replaceable.

---

📌 Intended Usage

Use KeystoneKMP as:

• A starting point for new KMP applications
• A reference architecture for modular mobile systems
• A foundation for scalable, feature-driven development

Clone, adapt, and trim modules based on your product needs.