Modern, Google-standard, AI-ready dual-purpose Android starter template built with Jetpack Compose Material 3, Clean Architecture, Unidirectional Data Flow (UDF), Hilt, Room, DataStore, and Retrofit — supporting both standard Android apps and 2D casual / puzzle / board games (including native Kotlin rewrites of Unity 2D games).
- Architecture Deep Dive: ARCHITECTURE.md
- AI Agent Guidelines: AGENTS.md
- Privacy Policy: PRIVACY-POLICY.md
- License: LICENSE
The :app module (io.github.amirisback.androidapp) is organized into four clean layers aligned with Google's Official Guide to App Architecture:
build-logic/convention/— Included Gradle composite build housing shared convention plugins (androidapp.android.application,androidapp.android.application.compose,androidapp.android.hilt,androidapp.android.room) and centralized app metadata (ProjectSetting.kt,ProjectAds.kt) backed bygradle/libs.versions.toml.core/— Shared utilities (core/common/), Hilt DI modules (core/di/), Material 3 theme & reusable Compose components (core/ui/), and an opt-in, decoupled 2D game engine core (core/game/: fixed-timestep loop,GameCanvas+GameSurfaceViewrenderers,SoundPool+ BGM audio manager,ImmersiveModeEffect, DataStore save store, and AdMob Rewarded controller).data/— Retrofit API service & DTOs (data/remote/), RoomAppDatabase/ DAO / entities (data/local/), bidirectional mappers (data/mapper/), andMealRepositoryImpl(data/repository/).domain/— 100% pure Kotlin immutable domain models (domain/model/), repository contracts (domain/repository/), and use cases (domain/usecase/) with zero Android or network framework imports.feature/— Standard app features (main,favorite,detail,about) plus a minimal opt-in game starter reference (game), all following UDF (*UiState+ViewModel+<Feature>Route+ stateless<Feature>Screenwith@Preview).
See ARCHITECTURE.md for the full package map, import boundary table, and step-by-step feature checklist.
Standard app features and the 2D game track are strictly decoupled and share only ProjectApplication.kt, core/common/, core/di/DispatcherModule.kt, core/ui/theme/, and build-logic/convention/:
- Default / Hybrid Mode:
MainActivityremains the default launcher with the Meal sample intact.core/game/andfeature/game/stay opt-in with zero startup overhead (MobileAdsInitProvideris removed viatools:node="remove"so non-game apps never initialize AdMob at launch). - Standard App Only (Prune Game Track): Delete
core/game/,feature/game/,core/di/GameModule.kt, their unit tests, and the.feature.game.GameActivitymanifest entry (optionally dropgoogle.play.services.ads/androidx.datastore.preferences). - 2D Casual / Puzzle / Board Game Only (Prune Meal Track): Delete
data/,domain/,feature/{main,detail,favorite,about}/,core/ui/component/MealCard.kt,core/di/{Database,Network,Repository,UseCase}Module.kt, and promote.feature.game.GameActivitytoMAIN/LAUNCHERinAndroidManifest.xml.
| Unity 2D Concept | Native Kotlin Equivalent |
|---|---|
FixedUpdate(dt) |
FixedTimestepClock + GameCanvas / GameSurfaceHost |
Time.timeScale = 0 / pause |
GameLoopController (IDLE / RUNNING / PAUSED) |
PlayerPrefs / local save |
GameSaveStore (DataStoreGameSaveStore with JSON slot) |
AudioSource (SFX + BGM) |
GameAudioController (SoundPool + MediaPlayer + GameAudioLifecycleEffect) |
| AdMob Rewarded Ads | RewardedAdController (AdMobRewardedAdController, IDs in ProjectAds.kt) |
Fullscreen + Screen.sleepTimeout |
ImmersiveModeEffect(enabled = true, keepScreenOn = true) |
See AGENTS.md and ARCHITECTURE.md for the exact file-by-file pruning checklists.
| Category | Technology & Version |
|---|---|
| SDK & JVM | minSdk 24 · compileSdk 37 · targetSdk 37 · JVM 17 |
| Build & Compiler | AGP 9.5.1 · Kotlin 2.4.21 · KSP 2.3.14 · Gradle 9.9.1 · Convention Plugins (build-logic/convention) |
| UI & Design | Jetpack Compose (BOM 2026.09.00) · Material 3 · Edge-to-Edge |
| Dependency Injection | Hilt 2.60.1 |
| Persistence | Room 2.8.5 (KSP schema export) · DataStore Preferences 1.3.0 |
| Networking | Retrofit · OkHttp · Gson · Chucker 4.4.0 |
| Image Loading | Coil 3.6.3 (coil-compose, coil-network-okhttp) |
| 2D Game Core (Opt-In) | Fixed-Timestep Loop · Compose Canvas / SurfaceView · SoundPool + MediaPlayer · WindowInsetsControllerCompat · Google Mobile Ads 25.5.0 |
| Async & State | Kotlin Coroutines · Flow · StateFlow (collectAsStateWithLifecycle) |
| Android Utilities | Frogo SDK 4.0.0 |
| Testing (JVM) | JUnit 4.13.2 · kotlinx-coroutines-test 1.10.2 |
- Update application metadata (
NAME_APP,APP_DOMAIN,APP_PLAY_CONSOLE,ADMOB_APP_ID, version code/name, database & preference names) inbuild-logic/convention/src/main/kotlin/io/github/amirisback/androidapp/convention/ProjectSetting.kt. - Update AdMob debug and release unit IDs (
BANNER_ID,INTERSTITIAL_ID,REWARDED_ID) inbuild-logic/convention/src/main/kotlin/io/github/amirisback/androidapp/convention/ProjectAds.kt. - Update
namespaceinapp/build.gradle.ktsand package directories if renaming the root package. - Pick your starter mode (Hybrid, Standard App Only, or 2D Game Only) and follow the pruning guide in ARCHITECTURE.md and AGENTS.md.
# Assemble debug APK & export Room schema via KSP
./gradlew assembleDebug
# Run JVM unit tests
./gradlew testDebugUnitTest
# Run Android Lint verification
./gradlew lintDebug| UI 1 | UI 2 | UI 3 |
|---|---|---|
![]() |
![]() |
![]() |
- Muhammad Faisal Amir (
faisalamircs@gmail.com)




