Android showcase

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.

Project characteristics and tech-stack

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.

• Tech-stack
  • 100% Kotlin + Coroutines - perform background operations
  • Retrofit - networking
  • Jetpack
    • Navigation - in-app navigation
    • LiveData - notify views about database change
    • Lifecycle - perform an action when lifecycle state changes
    • ViewModel - store and manage UI-related data in a lifecycle conscious way
    • Room - store offline cache
  • Kodein - dependency injection
  • Coil - image loading library
  • Lottie - animation library
  • Stetho - application debugging
• Modern Architecture
  • Clean Architecture (at feature module level)
  • Single activity architecture ( withNavigation component)
  • MVVM + MVI (presentation layer)
  • Dynamic feature modules
  • Android Architecture components (ViewModel, LiveData, Navigation)
  • Android KTX - Jetpack Kotlin extensions
• CI
  • GitHub Actions
  • Automatic PR verification including tests, linters and 3rd online tools
• Testing
  • Unit Tests (JUnit 5 via android-junit5)
  • UT Tests (Espresso)
  • Mockk - mocking framework
  • Kluent - assertion framework
• UI
  • Material design
  • Reactive UI
• Static analysis tools
  • Ktlint - validate code formating
  • Detekt - verify complexity look for and code smell
• Gradle
  • Gradle Kotlin DSL
  • Custom tasks
  • Plugins (SafeArgs, android-junit5)
  • Dependency locks
  • Versions catalog

Architecture

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

Module types and module dependencies

This is a diagram present dependencies between project modules (Gradle sub-projects).

Note that due usage of Android

dynamic-feature

app

We have three kinds of modules in the application:

• app

  module - 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.).
• application-specific

  library_x

  modules 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)
• feature modules - the most common type of module containing all code related to a given feature.

Feature module structure

Clean architecture

feature module

Notice that

app

module and

library_x

modules structure differs a bit from feature module structure.

Each feature module contains non-layer components and 3 layers with distinct set of responsibilities.

Presentation layer

This layer is closest to what the user sees on the screen. The

presentation

MVVM

ViewModel

MVI

actions

common state

LiveData

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

NavHostActivity

Domain layer

This is the core layer of the application. Notice that the

domain

domain

data

presentation

domain

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

domain

data layer

Data layer

Manages application data and exposes these data sources as repositories to the

domain

Components: - Repository is exposing data to the

domain

domain

domain

use case

• Mapper - maps

  data model

  to

  domain model

  (to keep

  domain

  layer independent from the

  data

  layer).
• RetrofitService - defines a set of API endpoints.
• DataModel - defines the structure of the data retrieved from the network and contains annotations, so Retrofit (Moshi) understands how to parse this network data (XML, JSON, Binary...) this data into objects.

Data flow

Below diagram presents application data flow when a user interacts with

album list screen

Dependency management

This project utilizes multiple mechanics to easily share the same versions of dependencies.

App library 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

MODULE_NAME/gradle.lockfile

To update lock files run

./gradlew test --write-locks

gradle.lockfile

Each feature module depends on the

app

Gradle plugin dependencies

Gradle plugins are defined in pluginManagement block (settings.gradle file).

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

pluginManagement

buildSrc

Shared dependencies

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

pluginManagement

CI pipeline

CI is utilizing GitHub Actions. Complete GitHub Actions config is located in the .github/workflows folder.

PR Verification

Series of workflows runs (in parallel) for every opened PR and after merging PR to

main

./gradlew lintDebug

./gradlew detekt

./gradlew ktlintCheck

./gradlew testDebugUnitTest

./gradlew connectedCheck

./gradlew :app:bundleDebug

Dependency updates

The update-dependencies task run periodically and creates a pull request containing dependency updates (updated gradle .lockfile files used by Gradle’s dependency locking).

Design decisions

Read related articles to have a better understanding of underlying design decisions and various trade-offs.

• Multiple ways of defining Clean Architecture layers
• More coming soon

What this project does not cover?

The interface of the app utilizes some of the modern material design components, however, is deliberately kept simple to focus on application architecture.

Upcoming improvements

Checklist of all upcoming enhancements.

Getting started

There are a few ways to open this project.

Android Studio

1. Android Studio

   ->

   File

   ->

   New

   ->

   From Version control

   ->

   Git

2. Enter

   https://github.com/igorwojda/android-showcase.git

   into URL field an press

   Clone

   button

Command-line + Android Studio

1. Run

   git clone https://github.com/igorwojda/android-showcase.git

   command to clone project
2. Open

   Android Studio

   and select

   File | Open...

   from the menu. Select cloned directory and press

   Open

   button

Inspiration

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.

Cheat sheet

• 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

Android projects

Other high-quality projects will help you to find solutions that work for your project:

• Iosched - official Android application from google IO 2019
• Android Architecture Blueprints v2 - a showcase of various Android architecture approaches
• Android sunflower complete

  Jetpack

  sample 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 state

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

Known issues

• ktlint

  import-ordering

  rule 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)
• False positive "Unused symbol" for a custom Android application class referenced in AndroidManifest.xml file (Issue 27971)
• False positive "Function can be private" (Issue KT-33610)
• False positive cannot access class (Issue 16077). This is fixed in InteliJ IDEA 2021.1 EAP 1 afair.
• Gradle has no way to share dependency versions between library and Gradle plugin or prod and test version of the library (Issue 16077)
• Android lint complains about exceeding access rights to ArchTaskExecutor Issue 79189568
• JUnit 5 does not support tests with suspended modifier (Issue 1914)
• Gradle dependencies can't be eaisly shared between app libraries and Gradle plugins https://github.com/gradle/gradle/issues/16077

Contribute

Want to contribute? Check our Contributing docs.

Author

License

MIT License

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.

Animations License

Flowing animations and are distributed under

Creative Commons License 2.0