Mobi

Mobi is a public reference architecture repository for Kotlin Multiplatform mobile work.

It demonstrates how to structure a modular shared Kotlin codebase, how to keep native Android and iOS shells explicit while still sharing meaningful feature state, and how to document architecture decisions in a way that stays useful as the code evolves.

This repository is not trying to be:

• a polished product app
• a minimal starter template
• a CI portability showcase first

Those concerns still matter here, but the primary value of Mobi is the architecture itself and the documentation around it.

What Mobi Demonstrates

• modular shared Kotlin layers for core, feature, dependency wiring, and shared UI
• native Android and iOS shells consuming the same shared feature state
• shared async feature state modeled explicitly instead of with ad hoc booleans
• repo-owned build and release orchestration that stays understandable from the codebase itself
• architecture documentation through ADRs and focused reference guides

Clean-Clone Quickstart

The reviewed baseline is Kotlin Toolchain 0.13.0. iOS development requires an Apple Silicon Mac; shared Kotlin targets iosArm64 devices and iosSimulatorArm64 simulators. Intel iOS simulators are outside Mobi's support policy. App minimums are iOS 26.0 and Android 16/API 36; Android compile SDK is API 37; target SDK remains API 36. These floors follow a configurable policy of one stable major behind the latest reviewed stable release. See the mobile support workflow and adoption evidence.

Install Android platform API 37 and build tools 37.0.0, and review/accept the Android SDK license explicitly before running Android jobs. See the local SDK setup.

Install Ruby dependencies:

bundle install

Install the pinned static-quality tools explicitly on macOS (Xcode command-line tools are required; the first run downloads artifacts and builds a private Ruby):

./scripts/ci/install_quality_tools.sh

Set a writable Kotlin Toolchain cache:

export KOTLIN_CLI_BOOTSTRAP_CACHE_DIR="$PWD/.kotlin-cache"

Run the main local smoke path:

./scripts/ci/run_job.sh android-build-debug
./scripts/ci/run_job.sh android-test
./scripts/ci/run_job.sh ios-build-debug
./scripts/ci/run_job.sh ios-test
./scripts/ci/run_job.sh quality-check

That path is the fastest way to validate that a clean clone can exercise the same repo-owned jobs used by CI.

For the Android smoke jobs, the repository generates ignored local debug signing files under android-app/ if no Android signing material has been provided. Release-oriented Android jobs still expect explicit signing inputs.

Start Here

If you are approaching this repo as a reader first, these are the most useful entry points:

• Mobile Architecture
• Platform Direction
• Architecture Decisions
• How To Add A Feature
• Local Development
• CI Validation And Release Candidates
• Secrets Reference
• iOS Gradle Bridge Migration
• Quality And Dependency Maintenance Audit

The iOS development path uses Kotlin Toolchain for KLib compilation and a tracked Swift-export producer for generated native Home/Nearby APIs. Xcode owns the app, native packages, tests and unsigned builds; one Kotlin archive also contains Shared UI. Gradle/unknown iOS builder overrides refuse; rollback restores complete content first. Credentialed iOS archive/export/TestFlight lanes are held pending separate signed-delivery evidence and authorization. The bridge has a separate removal change; complete published Git revisions preserve content rollback. See the integration decision and trade-offs.

Repository Shape

• project.yaml: Kotlin Toolchain workspace entry point
• shared-core/: platform-agnostic shared domain logic
• shared-feature-home/: shared feature contract and state
• shared-feature-nearby-vehicle-map/: rider-centered map state and refresh policy
• shared-di/: shared dependency graph and composition helpers
• shared-ios-app/: iOS composition and the shared UIKit entry point
• shared-ui-home/: shared Compose UI for the home feature
• android-app/: Android app shell
• ios-app/: iOS app shell
• tools/swift-export/: tracked standalone exporter, pending Toolchain integration
• docs/adr/: architecture decision records
• scripts/ci/run_job.sh: repo-owned job dispatcher
• fastlane/Fastfile: build and release lanes

Architecture And Operations

Even though this repository is not primarily a CI showcase, the operational layer is still part of the reference architecture.

The main pattern is:

• GitHub Actions stays thin
• repository scripts own the job contract
• Fastlane wraps build and release commands
• Kotlin Toolchain remains the multiplatform build entry point

That keeps the runtime and release mechanics close to the architecture instead of hiding them inside CI configuration alone.

Pull requests use conservative changed-path classification to avoid standalone native app builds for behavior-only changes. Scheduled validation runs the full test and release-configuration build surface for an exact main SHA. See CI Validation And Release Candidates for the selection rules, Apple test plans, and the distinction between an unsigned nightly validation candidate and a credentialed release artifact.

Linting and Static Analysis

The repository keeps quality checks behind repo-owned scripts instead of pushing tool orchestration into CI or the Gradle bridge.

• just format applies Kotlin and Swift formatting
• just lint checks Kotlin, Swift (including package source), and repository shell files, including new nonignored files
• just check runs those checks once, then selected native jobs in an owned source copy; stage the full intended content first
• just deps records a pinned dependency inventory and explicit coverage gaps

The pre-commit hook uses just check's script. CI's quality-check job uses explicit static mode without local staging requirements. See static gate inputs and recovery and staged validation and recovery. Use ./scripts/dev/check.sh --plan to inspect the staged job selection. quality-tools.json locks the analyzers, their private Ruby/Java runtimes, artifact checksums and rule profiles. Quality commands verify the installation offline; they never install or select tools from PATH.

The current tool split is:

• ktlint for Kotlin formatting checks and autofix
• detekt for Kotlin static analysis
• SwiftFormat for Swift formatting checks and autofix
• SwiftLint for Swift linting
• ShellCheck for repo-owned shell scripts

Dependency Maintenance

Renovate is the repository's dependency update orchestrator. The checked-in renovate.json covers GitHub Actions, Bundler, custom Kotlin Toolchain module.yaml Maven coordinates that generic Gradle tooling does not see. Native iOS dependencies such as TCA, Point-Free Dependencies, and MapLibre are declared in ios-app/Dependencies/Package.swift, so Renovate can manage them through its native Swift Package Manager support. Enable the Renovate GitHub App for hosted pull requests, or point a self-hosted Renovate runner at this repository. Metro runtime/compiler and Kotlin coroutines updates are grouped across Kotlin Toolchain modules. Reviewed ceilings remain Metro <=1.4.5 and Kotlin <=2.4.20. Toolchain 0.13.0 supplies Kotlin 2.4.20 and Compose 1.12.1. Android builds can still delegate to generated Gradle/AGP projects; the hand-maintained iOS bridge is removed separately. The scheduled compatibility watch measures the current direct mobile baseline and reports bounded release discovery and missing capabilities without adoption permission. Historical bridge receipts and contract fixtures retain their original scope. See the removal and recovery record.

Install the pinned discovery tools once, then record a local inventory:

./scripts/maintenance/install_tools.sh
just deps > /tmp/mobi-inventory.json

For manual compatibility assessment and isolated direct rehearsal:

./scripts/dev/dependency_updates.sh assess-compatibility
./scripts/dev/dependency_updates.sh prepare-kotlin
./scripts/dev/dependency_updates.sh rehearse-compatibility direct-mobile --store compatibility

The compatibility runner guide separates compile/link, full mobile and direct-path evidence, with review and cleanup steps. The scheduled caller uses the current direct baseline; historical watch scope is separate.

The just deps command uses verified Node/Renovate pins for isolated native extraction. It records declarations, locked packages and missing resolved graphs; it does not fetch update catalogs or claim a clean vulnerability scan. Missing tools fail with explicit setup guidance. The inventory guide covers source-bound release/advisory evidence, failure states and recovery. The inventory also includes the configured minimum-OS assessment. Use ./scripts/dev/dependency_updates.sh assess-support for the lightweight check. Architecture, API, support-window and Toolchain-default changes require an impact review and explicit adoption decision; the workflow does not automatically update source or retire the bridge. The support guide explains source freshness, candidate rehearsal and per-project configuration. The executor guide demonstrates independent Kotlin/Elixir rehearsal fixtures and safe cleanup before real native rehearsal.

Current Example Surface

The current sample app exposes three visible flows on both platforms:

• Native Home: a native shell consuming shared feature state
• Nearby Map: a lightweight native coordinate map consuming shared map state
• Shared UI: a shared Compose screen consuming the same home feature state

The home feature includes an asynchronous repository seam so both native shells and the shared UI can exercise the same loading, success, and failure states. The nearby map feature keeps map product rules in shared Kotlin while Android and iOS draw a functional rider-centered coordinate map without requiring an external map SDK or API key.

Contributing And Support

• Use GitHub Discussions for architecture questions and design conversations.
• Use GitHub Issues for bugs, docs gaps, and concrete improvement requests.
• See CONTRIBUTING.md for contribution guidance.
• See SECURITY.md for security reporting expectations.

Licensing

Code in this repository is licensed under the GNU Affero General Public License v3.0. Documentation and brand/trademark handling are intentionally treated separately. See the repository license files and notices for the current details.