How general-mobile/kotlin-android-mvvm-starter works
1. What this repo is
- This is a Cookiecutter-based Android Kotlin starter template, not a finished product app.
- The real generated project lives under {{cookiecutter.repo_name}}/, and hooks/post_gen_project.py suggests the repo is meant to scaffold a new app structure automatically.
2. Top-level build and project shape
- The project is a standard Gradle Android application with a single app module.
- Root files (build.gradle, settings.gradle, gradle/, gradlew) define the build, while app/build.gradle holds the Android module dependencies and configuration.
3. Overall architectural style
- The starter is organized around MVVM with clear separation between:
- UI screens in ui/
- presentation logic in BaseViewModel and screen-specific view models
- data/storage in db/
- wiring/dependency injection in di/
- The codebase is intentionally scaffolded around reusable base classes rather than feature-heavy implementations.
4. UI layer and app flow
- The main user-facing entry points are ui/splash/SplashActivity.kt and ui/main/MainActivity.kt.
- SplashActivity likely acts as the launch gate, then hands off to the main screen.
- MainActivity pairs with MainActivityViewModel, which is the primary example of the Activity + ViewModel boundary in this starter.
5. Shared Android abstractions
- The core/ package contains reusable base classes for the app layer:
- BaseActivity, BaseFragment
- BaseViewModel
- adapter/view-holder helpers for list rendering
- BaseEntity and diffing helpers for model-driven UI updates
- This indicates the repo is designed to reduce repeated boilerplate across future screens and lists.
6. Persistence boundary
- The db/ package defines a local data layer centered on AppDatabase, ExampleDao, and Example entity.
- The presence of database, DAO, and entity packages suggests a Room-style local storage boundary.
- Even though only example artifacts are shown, the structure is set up so UI/view models do not talk directly to tables; they should go through DAOs or repository-like intermediates.
7. Dependency injection and composition
- di/ is the composition root for the app and is organized with:
- ApplicationComponent
- ApplicationModule, DatabaseModule, NetModule
- ActivityScope
- This means object creation is centralized, with the application graph supplying shared services like database and networking components, and scoped objects for activities.
8. Network and remote-service boundary
- There are no concrete API clients in the tree, but NetModule and utils/service/CallbackWrapper.kt show that the template is prepared for Retrofit/OkHttp-style asynchronous remote calls.
- The architecture boundary is therefore: UI/ViewModel layer calls into service abstractions, which are injected through DI and wrapped for callback/error handling.
9. Cross-cutting utilities
- utils/extensions/ provides Kotlin extension functions for Activity, Fragment, View, Context, and generic types.
- utils/timber/CrashReportTree.kt indicates app-wide logging/crash reporting integration through Timber.
- These are support layers, not business logic, but they are important because they influence how screens interact with Android framework objects and diagnostics.
10. Testing structure
- The repo includes both:
- src/test for local JVM unit tests
- src/androidTest for instrumented UI tests
- ApplicationTest.kt and ExampleUnitTest.kt show the starter is prepared for both logic-level and device/emulator-level validation, with Espresso mentioned in the README for UI testing.
11. Resources and app shell
- res/ contains the minimal Android shell: launcher assets, activity_main.xml, colors, dimensions, styles, and a splash drawable.
- This matches the architecture: UI is mostly code-driven via Activities/ViewModels, with XML layouts providing the view shell.
12. External libraries that shape the architecture
- The README shows the template is designed to support:
- RxJava/RxAndroid/RxKotlin for async flow
- Coroutines as an alternative async model
- Retrofit/OkHttp/Gson for remote data
- Dagger 2 for DI
- Timber and Crashlytics for observability
- Picasso for image loading
- Jetpack Architecture Components for MVVM primitives
- The repo is therefore a starter that can be wired into several common Android data-flow styles, but the package structure is centered on MVVM + DI + local/remote data boundaries.
Main entry points: build.gradle App module · MainActivity.kt Main screen · ApplicationComponent.kt DI graph · MainActivityViewModel.kt Main VM
Components 20
Template scaffold
Cookiecutter files and generation hook that shape the starter project.
- Cookiecutter · Template variables and repository generation inputs.
cookiecutter.json - Post-gen hook · Runs after project generation to finalize the scaffold.
hooks/post_gen_project.py
Android app
The generated Gradle Android application and its app module.
- Root build · Top-level Gradle configuration for the starter repository.
{{cookiecutter.repo_name}}/build.gradle - Settings · Declares the generated project modules.
{{cookiecutter.repo_name}}/settings.gradle - App module · Single Android application module containing code, resources, and tests.
{{cookiecutter.repo_name}}/app/build.gradle - Manifest · Declares the application and Android component entry points.
{{cookiecutter.repo_name}}/app/src/main/AndroidManifest.xml - Splash · Launch gate that starts the app flow.
{{cookiecutter.repo_name}}/app/src/main/java/ui/splash/SplashActivity.kt - Main screen · Primary user-facing screen for the starter app.
{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivity.kt
Support layers
Reusable base classes, data access, DI, utilities, and resources.
- App class · Application subclass that anchors process-wide initialization.
{{cookiecutter.repo_name}}/app/src/main/java/App.kt - Main VM · Presentation logic paired with the main activity.
{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt - Core base · Shared Activity, Fragment, ViewModel, adapter, and diffing abstractions.
{{cookiecutter.repo_name}}/app/src/main/java/core - Database · Local persistence boundary centered on database, DAO, and entity layers.
{{cookiecutter.repo_name}}/app/src/main/java/db/AppDatabase.kt - Example DAO · Representative DAO for local reads and writes.
{{cookiecutter.repo_name}}/app/src/main/java/db/dao/ExampleDao.kt - Example entity · Representative persisted model used by the local data layer.
{{cookiecutter.repo_name}}/app/src/main/java/db/entities/Example.kt - DI graph · Application component, modules, and scopes for object composition.
{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt - Net module · Networking-oriented DI module prepared for remote service integration.
{{cookiecutter.repo_name}}/app/src/main/java/di/module/NetModule.kt - Utilities · Framework extensions, callback wrapping, and crash logging support.
{{cookiecutter.repo_name}}/app/src/main/java/utils - Resources · Layouts, drawables, values, and launcher assets for the app shell.
{{cookiecutter.repo_name}}/app/src/main/res
Tests
Local and instrumented validation entry points.
- Unit tests · Local JVM test entry point.
{{cookiecutter.repo_name}}/app/src/test/java/ExampleUnitTest.kt - Android tests · Device or emulator test entry point.
{{cookiecutter.repo_name}}/app/src/androidTest/java/ApplicationTest.kt
Connections 21
- Cookiecutter → Post-gen hook: generates · Template variables feed the project-generation hook.
- Post-gen hook → Root build: creates · The hook materializes the generated app structure.
- Root build → Settings: includes · Root Gradle wiring resolves the module list.
- Settings → App module: registers · The generated project is centered on a single app module.
- App module → Manifest: packages · Module build output is anchored by the Android manifest.
- App module → App class: starts · Application class is the process-wide entry point.
- Manifest → Splash: launches · Manifest declares the splash screen as a startup activity.
- Splash → Main screen: hands off · Splash gate transitions into the main screen.
- Main screen → Main VM: binds · Main activity delegates presentation logic to its view model.
- Main screen → Resources: renders · The screen is backed by XML layouts and app resources.
- Main VM → Core base: extends · View models rely on shared base classes and UI helpers.
- Main screen → Core base: uses · Activities inherit common Android abstractions from the core layer.
- Core base → Utilities: shares · Reusable framework helpers support activities, fragments, and views.
- DI graph → Database: provides · Composition root wires the local persistence boundary.
- DI graph → Net module: provides · Composition root also prepares remote-service wiring.
- DI graph → Main VM: injects · Presentation objects are created through the DI graph.
- Database → Example DAO: exposes · Database layer exposes DAO access.
- Example DAO → Example entity: maps · DAO operations act on persisted entities.
- Utilities → App class: logs · Crash-reporting tree plugs into the application lifecycle.
- App module → Unit tests: tests · Module includes local JVM validation.
- App module → Android tests: tests · Module includes instrumented validation.