mobile-android is an application development framework - a toolkit - for people who build android apps using kotlin. Its goal is to enable you to develop projects much faster than you could if you were writing code from scratch, by providing a rich set of libraries for commonly needed tasks, as well as a simple interface and logical structure to access these libraries.
This lets you creatively focus on your project by minimizing the amount of code needed for a given task.
The app is no-frills, but sufficiently complex that you can use it as a template to build upon.
Just click on button to create a new repo starting from this template.
- Architecture
- ViewModel - Store UI-related data that isn't destroyed on app rotations. Easily schedule asynchronous tasks for optimal execution.
- LiveData - Build data objects that notify views when the underlying database changes.
- Lifecycles - Create a UI that automatically responds to lifecycle events.
- Data Binding - Library that allows you to bind UI components in your layouts to data sources in your app using a declarative format rather than programmatically.
- Dependency Injection
- HILT - Hilt is built on top of the popular DI library Dagger to benefit from the compile time correctness, runtime performance, scalability, and Android Studio support that Dagger provides. Recommended by Android.
- Logging
- Timber - A logger with a small, extensible API which provides utility on top of Android's normal Log class.
- OkHttp Logging Interceptor
- Database
- Room - Store offline database
- Networking
- Retrofit - A type-safe HTTP client for Android
- Coroutines - Light wight threads for asynchronous programming
- CI
- GitHub Actions
- Automatic PR verification including tests, linters and sonarqube analysis
- Gradle
- Test - An Android testing framework for unit and runtime UI tests. Given When Then — Our Testing Approach
- Unit Tests (JUnit 5 via android-junit5)
- UT Tests (Espresso)
- Mockk
- Clean Architecture
- Adhering to SOLID Principles
- Repository Pattern for code separations
- Dependency Injection
- Simple Network Layer
- Simple Data Layer
- Better Logging
- Automatic Error Handling
- Media Selection Module
- Generic Permission Handler
- Flavors Sample
- Unit & Integration Tests
- CI for build release
- CD (TODO)
- Use SonarQube Analysis & generate reports
- Crashlytics/Analytics
This template is using Gradle Kotlin DSL as well as the Plugin DSL to setup the build.
Dependencies are inside the *.kt files in the buildSrc folder. This provides convenient auto-completion when writing your gradle files.
-
MVVM - Model View ViewModel
- Robust, testable, and maintainable app with classes for managing your UI component lifecycle and handling data persistence.
To learn more about the different architecture approach see, Common Architecture Design Patterns
-
Clean Architecture for separation of concern & modular approach
-
Every Activity/Fragment needs to extend BaseActivity/BaseFragment
-
Every Activity will have a DataBinding object and ViewModel object defined in this way:
abstract class BaseActivity<B : ViewDataBinding, VM : BaseViewModel> : AppCompatActivity() {
To learn more about the app architecture see Architecture Overview
Following diagram shows the diagram of how the request & response flow works for the boilerplate,
- Architecture Overview
- Request Manager
- Automatic Exception Handling
- Generic Runtime Permission Handler
- GeoLocation Tracker
- Biometric Authenticator
- Media Selection
- Database
- Network
- Crashlytics
- Logger
- Dependency Injection
- App Testing
Folder structure options and naming conventions for software projects
app # Application core implementation
├── .github/workflows # Github workflow files
├── buildSrc # Kotlin DSL for setup build & dependencies
├── crash-reporting # Crash reporting module/lib
├── biometric # Biometric Authenticator
├── data # Layer exposes all data source
├── domain # Domain layer contains all the use cases of your application
├── presentation # Prepares data for the application layer & maintains state
├── errors # Exception handling pure Kotlin implementation
├── errors-android # Exception handling android counterpart implementation
├── geolocation # Module to track user geolocation
├── media-android # Media Picker pure Kotlin implementation
├── media-library # Media Picker android counterpart implementation
├── permissions # Permission handling pure Kotlin implementation
├── permissions-android # Permission handling android counterpart implementation
├── logger # Text-based logging library
├── screenshots # Project screenshots
├── utils # Project utils
└── wiki # Documentation files
Use short lowercase names at least for the top-level files and folders except
LICENSE,README.md
app
├── ...
└── wiki
└── docs # Documentation files
├── contribution
│ └── CONTRIBUTING.md # Contribution doc
├── discussion # WHY-Series documents
│ ├── COMMON_ANDROID_ARCHITECTURAL_PATTERNS.md
│ ├── WHEN_COROUTINES_AND_RxJAVA.md
│ ├── WHY_DEPENDENCY_INJECTION.md
│ ├── WHY_KOTLIN.md
│ └── WHY_REPOSITORY.md
├── guide # Project practices guides
│ ├── KOTLIN_STYLE_GUIDE.md
│ ├── VERSIONING_GUIDE.md
│ └── XML_STYLE_GUIDE.md
└── modules
├── assets # Wiki Artifacts
└── *.md # Module level wiki documents
Automated tests are usually placed into the test or, less commonly, into the tests folder.
Q: Why tests are placed into a separate folder, as opposed to having them closer to the code under test?
A: Because you don't want to test the code, you want to test the program.
.
├── ...
├── src
│ ├── androidTest/ # Instrumented test, which will execute on an Android device
│ ├── ..
│ └── test/ # Example local unit test, which will execute on the development machine (host)
└── ...
CI is utilizing GitHub Actions. Complete GitHub Actions config is located in the .github/workflows folder.
Series of workflows runs (in parallel) for every opened PR and after merging PR to main branch:
./gradlew lintDebug- Runs Android lint./gradlew testDebugUnitTest- Run unit tests./gradlew build sonarqube --info- Analyzing Using Gradle Sonar Plugin
To learn more about contributing to this project see Guiding principles for contributing
- Why Kotlin?
- Why MVVM & Common Android Archiectural Patterns
- When I can choose Coroutines or RX-Kotlin to do some behaviour
- Why Dependency Injection? Why HILT?
- Why should you use the repository pattern?
Checklist of all upcoming enhancements.
This is project is a sample, to inspire you and should handle most of the common cases, but please take a look at additional resources.
- Core App Quality Checklist - learn about building the high-quality app
- Android Ecosystem Cheat Sheet - board containing 200+ most important tools
- Kotlin Coroutines - Use Cases on Android - most popular coroutine usages
Other high-quality projects will help you to find solutions that work for your project:
- Android Architecture Blueprints v2 - a showcase of various Android architecture approaches
- Android sunflower complete
Jetpacksample covering all libraries - GithubBrowserSample - multiple small projects demonstrating usage of Android Architecture Components
- Plaid - a showcase of Android material design
- Clean Architecture boilerplate - contains nice diagrams of Clean Architecture layers
- Android samples - official Android samples repository
- Roxie - solid example of
common stateapproach together witch very good documentation - Kotlin Android template - template that lets you create an Android/Kotlin project and be up and running in a few seconds.
- delay(timeMillis: 1L) added to avoid manual Resource state emission. (Issue 25)
Contributions are welcome from anyone and everyone. We encourage you to review the guiding principles for contributing