💎 Android application following best practices: Kotlin, Coroutines, JetPack, Clean Architecture, Feature Modules, Tests, MVVM, DI, Static Analysis...
Showcase is a sample project that presents a modern, 2021 approach to Android application development.
The goal of the project is to combine popular libraries/tools and demonstrate best developement practices by utilizing up to date tech-stack and presenting modern Android application Architecture that is modular, scalable, maintainable, and testable. This application may look simple, but it has all the pieces that will provide the rock-solid foundation for the larger app suitable for bigger teams and long application lifecycle.
This project is being maintained to match industry standards. Please check CONTRIBUTING page if you want to help.
This project takes advantage of best practices, many popular libraries and tools in the Android ecosystem. Most of the libraries are in the stable version unless there is a good reason to use non-stable dependency.
Feature related code is placed inside one of the feature modules. We can think about each feature as the equivalent of microservice or private library.
The modularized code-base approach provides few benefits: - better separation of concerns. Each module has a clear API., Feature related classes life in different modules and can't be referenced without explicit module dependency. - features can be developed in parallel eg. by different teams - each feature can be developed in isolation, independently from other features - faster compile time
This is a diagram present dependencies between project modules (Gradle sub-projects).
Note that due usage of Android
dynamic-featuremodule dependencies are reversed (feature modules are depending on
appmodule, not another way around).
We have three kinds of modules in the application:
appmodule - this is the main module. It contains code that wires multiple modules together (dependency injection setup,
NavHostActivity, etc.) and fundamental application configuration (retrofit configuration, required permissions setup, custom application class, etc.).
library_xmodules that some of the features could depend on. This is helpful if you want to share some assets or code only between few feature modules (currently app has no such modules)
Clean architectureis the "core architecture" of the application, so each
feature modulecontains own set of Clean architecture layers:
Notice thatappmodule andlibrary_xmodules structure differs a bit from feature module structure.
Each feature module contains non-layer components and 3 layers with distinct set of responsibilities.
This layer is closest to what the user sees on the screen. The
presentationlayer is a mix of
ViewModelused to preserve data across activity restart) and
common stateof the view and then new state is edited to a view via
LiveDatato be rendered).
common state(for each view) approach derives from Unidirectional Data Flow and Redux principles.
Components: - View (Fragment) - presents data on the screen and pass user interactions to View Model. Views are hard to test, so they should be as simple as possible. - ViewModel - dispatches (through
LiveData) state changes to the view and deals with user interactions (these view models are not simply POJO classes). - ViewState - common state for a single view - NavManager - singleton that facilitates handling all navigation events inside
NavHostActivity(instead of separately, inside each view)
This is the core layer of the application. Notice that the
domainlayer is independent of any other layers. This allows to make domain models and business logic independent from other layers. In other words, changes in other layers will have no effect on
domainlayer eg. changing database (
datalayer) or screen UI (
presentationlayer) ideally will not result in any code change withing
Components: - UseCase - contains business logic - DomainModel - defies the core structure of the data that will be used within the application. This is the source of truth for application data. - Repository interface - required to keep the
domainlayer independent from the
data layer(Dependency inversion).
Manages application data and exposes these data sources as repositories to the
domainlayer. Typical responsibilities of this layer would be to retrieve data from the internet and optionally cache this data locally.
Components: - Repository is exposing data to the
domainlayer. Depending on application structure and quality of the external APIs repository can also merge, filter, and transform the data. The intention of these operations is to create high-quality data source for the
domainlayer, not to perform any business logic (
domain model(to keep
domainlayer independent from the
Below diagram presents application data flow when a user interacts with
album list screen:
This project utilizes multiple mechanics to easily share the same versions of dependencies.
External dependencies (libraries) are defined using versions catalog feature in the settings.gradle file. These dynamic library versions are locked using Gradle docking dependency mechanism - concrete dependency versions are stored in
To update lock files run
./gradlew test --write-lockscommand and commit updated
gradle.lockfilefiles to repository.
Each feature module depends on the
appmodule, so dependencies are shared without need to add them explicitly in each feature module.
Dynamic versions aren't supported for Gradle plugins, so docking dependency mechanism can't be used (like for app library dependencies), and thus versions of some libraries & plugins have to be hardcoded in the gradle.properties file.
There is no easy way to share id between
buildSrcfolder, so plugin ids (also used within build scripts), have to be duplicated in the GradlePluginId file.
Gradle is missing proper build-in mechanism to share dependency versions between app library dependency and Gradle plugin dependency eg. Navigation component library uses Safe Args Gradle plugin with the same version.
To enable sharing all versions that are used for both plugins and libraries are defined in gradle.properties.
Unfortunately this technique cannot be applied to older Gradle plugins (added by
classpath, not by
pluginManagement), so some version in the gradle.properties are still duplicated.
Series of workflows runs (in parallel) for every opened PR and after merging PR to
./gradlew lintDebug- runs Android lint *
./gradlew detekt- runs detekt *
./gradlew ktlintCheck- runs ktlint *
./gradlew testDebugUnitTest- run unit tests *
./gradlew connectedCheck- run UI tests *
./gradlew :app:bundleDebug- create app bundle
Read related articles to have a better understanding of underlying design decisions and various trade-offs.
The interface of the app utilizes some of the modern material design components, however, is deliberately kept simple to focus on application architecture.
Checklist of all upcoming enhancements.
There are a few ways to open this project.
From Version control->
https://github.com/igorwojda/android-showcase.gitinto URL field an press
git clone https://github.com/igorwojda/android-showcase.gitcommand to clone project
Android Studioand select
File | Open...from the menu. Select cloned directory and press
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.
Other high-quality projects will help you to find solutions that work for your project:
Jetpacksample covering all libraries
common stateapproach together witch very good documentation
import-orderingrule conflicts with IDE default formatting rule, so it have to be disabled. This is partially fixed in AS 4.2 (see Issue 527 and Issue KT-10974)
Want to contribute? Check our Contributing docs.
Copyright (c) 2019 Igor Wojda
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 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Flowing animations and are distributed under
Creative Commons License 2.0: - Error screen by Chetan Potnuru - Building Screen by Carolina Cajazeira