Math Alarm ⏰

A Kotlin Multiplatform alarm app for Android and iOS where you solve math problems of varying difficulty to dismiss the alarm. Built with Clean Architecture and shared Kotlin ViewModels, Android Compose, and a native SwiftUI development UI.

Architecture

The project follows Clean Architecture with the MVVM pattern:

• :androidApp - All Compose screens/navigation/theme/localization/resources, application entry points and Android platform wiring
• :shared - UI-free feature ViewModels, application coordination, data and platform service adapters
• :core - Shared domain logic and business rules
• iosApp/ - SwiftUI screens and session/navigation owners consuming the app framework produced by :shared

The native migration uses shared Kotlin ViewModels and alarm logic with Compose on Android and SwiftUI on iOS. All native parity screens are implemented. Permanent XCTest/UI targets, native client flows, renderer/resource gates and archive checks are documented in architecture and build and testing. Migration progress separates implementation evidence from physical AlarmKit, acoustic, minimum-runtime and release acceptance gates. This development build is not yet release ready.

Technologies Used

Kotlin Multiplatform

• Kotlin Multiplatform - Share code between Android and iOS
• Compose Multiplatform - Android declarative UI renderer

UI & Navigation

• Material 3 - Modern Material Design components
• Navigation 3 - Android Compose navigation
• Compottie - Android Compose Lottie animations

Data & Storage

• Room KMP - Multiplatform database with SQLite
• Multiplatform Settings - Key-value storage across platforms
• Kotlinx Serialization - JSON serialization

Dependency Injection

• Koin - Lightweight dependency injection framework for KMP

Async & Reactive

• Coroutines - Asynchronous programming
• Kotlinx DateTime - Multiplatform date/time library

Logging & Analytics (Android)

• Kermit - Multiplatform logging library
• Firebase Analytics - App analytics
• Firebase Crashlytics - Crash reporting

Localization

• Lyricist - Type-safe string localization for Compose

Testing

See the testing guide for host suites, real-device lifecycle checks, CI, and physical-device release validation.

• Kotlin Test - Multiplatform testing
• Turbine - Flow testing
• Kotest - Assertions library
• MockK - Mocking library (Android)
• XCTest / XCUITest - Production framework, native owners, navigation and fresh-process restoration
• Maestro - Native client flows and software-keyboard/accessibility-size evidence

Installation

Math Alarm requires a minimum API level of 26 (Android 8.0+).

# Clone the repository
git clone https://github.com/t-regbs/MathAlarm.git

# Open in Android Studio or IntelliJ IDEA

Building for iOS

The iOS app supports iPhone and iPad running iOS/iPadOS 26 or later. The current build is verified locally with Xcode 27.0 and JDK 21. Open the shared iosApp scheme in iosApp/iosApp.xcodeproj, or run:

./gradlew :core:iosSimulatorArm64Test :shared:iosSimulatorArm64Test --continue
xcodebuild -project iosApp/iosApp.xcodeproj -scheme MathAlarmNative -configuration Debug \
  -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO build

The PR workflow runs permanent native tests, client flows, nine-locale screenshots and archive packaging on the GitHub-hosted xcode-27 Apple Silicon image, explicitly selecting Xcode 27.0 (27A266a). Use iPad simulators for layout/navigation checks and a physical iPhone for AlarmKit delivery and audio validation. Signed device builds require your Apple development team and provisioning profile; a simulator build does not establish alarm delivery reliability.

Contribution

All contributions are welcome. Simply make a PR!

LICENSE

MIT License

Copyright (c) 2025 Timilehin Aregbesola

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.