# general-mobile/kotlin-android-mvvm-starter architecture

> Architecture diagram of the GitHub repository general-mobile/kotlin-android-mvvm-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/general-mobile/kotlin-android-mvvm-starter
- Repository: https://github.com/general-mobile/kotlin-android-mvvm-starter

## Overview

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: [`{{cookiecutter.repo_name}}/app/build.gradle`](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/build.gradle) (App module), [`{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivity.kt`](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivity.kt) (Main screen), [`{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt`](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt) (DI graph), [`{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt`](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt) (Main VM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scaffold["Template scaffold"]
  node_cookiecutter["Cookiecutter<br/>template config<br/>[cookiecutter.json]"]
  node_postgen["Post-gen hook<br/>scaffold hook"]
end

subgraph group_android["Android app"]
  node_rootbuild["Root build<br/>gradle root<br/>[build.gradle]"]
  node_settings["Settings<br/>[settings.gradle]"]
  node_appmodule["App module<br/>android module<br/>[build.gradle]"]
  node_manifest["Manifest<br/>app entry"]
  node_splash["Splash<br/>activity<br/>[SplashActivity.kt]"]
  node_mainui["Main screen<br/>activity<br/>[MainActivity.kt]"]
end

subgraph group_support["Support layers"]
  node_appentry["App class<br/>[App.kt]"]
  node_mainvm["Main VM<br/>viewmodel"]
  node_core["Core base<br/>android base<br/>[core]"]
  node_database[("Database<br/>room-style storage<br/>[AppDatabase.kt]")]
  node_dao["Example DAO<br/>data access<br/>[ExampleDao.kt]"]
  node_entity["Example entity<br/>db model<br/>[Example.kt]"]
  node_di{{"DI graph<br/>dagger setup"}}
  node_netmod["Net module<br/>service wiring<br/>[NetModule.kt]"]
  node_utils["Utilities<br/>shared helpers<br/>[utils]"]
  node_resources["Resources<br/>android res<br/>[res]"]
end

subgraph group_tests["Tests"]
  node_unit["Unit tests<br/>jvm tests<br/>[ExampleUnitTest.kt]"]
  node_androidtest["Android tests<br/>instrumented tests<br/>[ApplicationTest.kt]"]
end

node_cookiecutter -->|"generates"| node_postgen
node_postgen -->|"creates"| node_rootbuild
node_rootbuild -->|"includes"| node_settings
node_settings -->|"registers"| node_appmodule
node_appmodule -->|"packages"| node_manifest
node_appmodule -->|"starts"| node_appentry
node_manifest -->|"launches"| node_splash
node_splash -->|"hands off"| node_mainui
node_mainui -->|"binds"| node_mainvm
node_mainui -->|"renders"| node_resources
node_mainvm -->|"extends"| node_core
node_mainui -->|"uses"| node_core
node_core -->|"shares"| node_utils
node_di -->|"provides"| node_database
node_di -->|"provides"| node_netmod
node_di -->|"injects"| node_mainvm
node_database -->|"exposes"| node_dao
node_dao -->|"maps"| node_entity
node_utils -->|"logs"| node_appentry
node_appmodule -->|"tests"| node_unit
node_appmodule -->|"tests"| node_androidtest

click node_cookiecutter "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/cookiecutter.json"
click node_postgen "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/hooks/post_gen_project.py"
click node_rootbuild "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/build.gradle"
click node_settings "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/settings.gradle"
click node_appmodule "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/build.gradle"
click node_manifest "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/AndroidManifest.xml"
click node_appentry "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/App.kt"
click node_splash "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/splash/SplashActivity.kt"
click node_mainui "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivity.kt"
click node_mainvm "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt"
click node_core "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/core"
click node_database "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/AppDatabase.kt"
click node_dao "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/dao/ExampleDao.kt"
click node_entity "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/entities/Example.kt"
click node_di "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt"
click node_netmod "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/di/module/NetModule.kt"
click node_utils "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/utils"
click node_resources "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/res"
click node_unit "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/test/java/ExampleUnitTest.kt"
click node_androidtest "https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/androidTest/java/ApplicationTest.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cookiecutter,node_postgen toneBlue
class node_rootbuild,node_settings,node_appmodule,node_manifest,node_splash,node_mainui toneAmber
class node_appentry,node_mainvm,node_core,node_database,node_dao,node_entity,node_di,node_netmod,node_utils,node_resources toneMint
class node_unit,node_androidtest toneRose
```

## Components

### Template scaffold

Cookiecutter files and generation hook that shape the starter project.

- [Cookiecutter](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/cookiecutter.json): template config · Template variables and repository generation inputs. · `cookiecutter.json`
- [Post-gen hook](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/hooks/post_gen_project.py): scaffold 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](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/build.gradle): gradle root · Top-level Gradle configuration for the starter repository. · `{{cookiecutter.repo_name}}/build.gradle`
- [Settings](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/settings.gradle): gradle settings · Declares the generated project modules. · `{{cookiecutter.repo_name}}/settings.gradle`
- [App module](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/build.gradle): android module · Single Android application module containing code, resources, and tests. · `{{cookiecutter.repo_name}}/app/build.gradle`
- [Manifest](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/AndroidManifest.xml): app entry · Declares the application and Android component entry points. · `{{cookiecutter.repo_name}}/app/src/main/AndroidManifest.xml`
- [Splash](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/splash/SplashActivity.kt): activity · Launch gate that starts the app flow. · `{{cookiecutter.repo_name}}/app/src/main/java/ui/splash/SplashActivity.kt`
- [Main screen](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivity.kt): activity · 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](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/App.kt): application · Application subclass that anchors process-wide initialization. · `{{cookiecutter.repo_name}}/app/src/main/java/App.kt`
- [Main VM](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt): viewmodel · Presentation logic paired with the main activity. · `{{cookiecutter.repo_name}}/app/src/main/java/ui/main/MainActivityViewModel.kt`
- [Core base](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/core): android base · Shared Activity, Fragment, ViewModel, adapter, and diffing abstractions. · `{{cookiecutter.repo_name}}/app/src/main/java/core`
- [Database](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/AppDatabase.kt): room-style storage · Local persistence boundary centered on database, DAO, and entity layers. · `{{cookiecutter.repo_name}}/app/src/main/java/db/AppDatabase.kt`
- [Example DAO](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/dao/ExampleDao.kt): data access · Representative DAO for local reads and writes. · `{{cookiecutter.repo_name}}/app/src/main/java/db/dao/ExampleDao.kt`
- [Example entity](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/db/entities/Example.kt): db model · Representative persisted model used by the local data layer. · `{{cookiecutter.repo_name}}/app/src/main/java/db/entities/Example.kt`
- [DI graph](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt): dagger setup · Application component, modules, and scopes for object composition. · `{{cookiecutter.repo_name}}/app/src/main/java/di/component/ApplicationComponent.kt`
- [Net module](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/di/module/NetModule.kt): service wiring · Networking-oriented DI module prepared for remote service integration. · `{{cookiecutter.repo_name}}/app/src/main/java/di/module/NetModule.kt`
- [Utilities](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/java/utils): shared helpers · Framework extensions, callback wrapping, and crash logging support. · `{{cookiecutter.repo_name}}/app/src/main/java/utils`
- [Resources](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/main/res): android res · 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](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/test/java/ExampleUnitTest.kt): jvm tests · Local JVM test entry point. · `{{cookiecutter.repo_name}}/app/src/test/java/ExampleUnitTest.kt`
- [Android tests](https://github.com/general-mobile/kotlin-android-mvvm-starter/blob/master/{{cookiecutter.repo_name}}/app/src/androidTest/java/ApplicationTest.kt): instrumented tests · Device or emulator test entry point. · `{{cookiecutter.repo_name}}/app/src/androidTest/java/ApplicationTest.kt`

## Connections

- 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.
