A sample modern Kotlin application - Documentation still under maintenance

This project is a sample that presents modern, the recent approach to Android application development using Kotlin and latest technology stack.

The goal of the project is to demonstrate best practices, provide a set of guidelines, and present modern Android application architecture that is modular, scalable, maintainable and testable. This application may look simple, but it has all of these small details that will set the rock-solid foundation of the larger app suitable for bigger teams and long application lifecycle management.

💥 Powered by TvMaze.

Table of Contents

• Development
  • Environment setup
  • Code style
• Design
• Architecture
  • Modules
    • App module
    • Base module
    • Data module
    • Domain module
    • Test shared module
  • Architecture components
• Documentation
• Tech-stack
  • Patterns
  • Dependencies
  • Test dependencies
  • Plugins
• Resources
  • Projects
  • Articles
  • Libraries
  • Best practices
  • Codelabs
• Contributions
• Roadmap
• License

Development

Environment setup

First off, you require the latest Android Studio 3.5 (or newer) to be able to build the app.

• TvMaze: https://www.tvmaze.com/api

Moreover, to sign your app for release you should generate an upload key and keystore following the official documentation. Append the information used to generate it into local.properties project root file following the structure:

#Signing Config
signing.key.alias = <insert>
signing.key.password = <insert>
signing.store.file = <insert>
signing.store.password = <insert>

Code style

To maintain the style and quality of the code, are used the bellow static analysis tools. All of them use properly configuration and you find them in the project root directory .{toolName}.

All these tools are integrated in pre-commit git hook, in order ensure that all static analysis and tests passes before you can commit your changes. To skip them for specific commit add this option at your git command:

git commit --no-verify

The pre-commit git hooks have exactly the same checks as CircleCI and are defined in this script. This step ensures that all commits comply with the established rules. However the continuous integration will ultimately be validated that the changes are correct.

Design

App support different screen sizes and the content has been adapted to fit for mobile devices and tablets. To do that, it has been created a flexible layout using one or more of the following concepts:

• Use ConstraintLayout
• Avoid hard-coded layout sizes
• Create alternative layouts
• Use the smallest width qualifier
• Use the available width qualifier
• Add orientation qualifiers

In terms of design has been followed recommendations Android Material Design comprehensive guide for visual, motion, and interaction design across platforms and devices. Granting the project in this way a great user experience (UX) and user interface (UI). For more info about UX best practices visit link.

Moreover, has been implemented support for dark theme with the following benefits:

• Can reduce power usage by a significant amount (depending on the device’s screen technology).
• Improves visibility for users with low vision and those who are sensitive to bright light.
• Makes it easier for anyone to use a device in a low-light environment.

Architecture

The architecture of the application is based, apply and strictly complies with each of the following 5 points:

• Android architecture components, part of Android Jetpack for give to project a robust design, testable and maintainable.
• Pattern Model-View-ViewModel (MVVM) facilitating a separation of development of the graphical user interface.
• S.O.L.I.D design principles intended to make software designs more understandable, flexible and maintainable.
• Modular app architecture allows to be developed features in isolation, independently from other features.

Modules

Modules are collection of source files and build settings that allow you to divide a project into discrete units of functionality. In this case apart from dividing by functionality/responsibility, existing the following dependence between them:

The above graph shows the app modularisation:

• :app module depends on :base, :data, :domain and :test-shared
• :data module depends on :base and :test-shared.
• :domain module depends on :base, :data and :test-shared
• :base doesn’t have any dependency.

App module

The :app module is an com.android.application, which is needed to create the app bundle. It is also responsible for initiating the dependency graph, play core and another project global libraries, differentiating especially between different app environments.

Base module

The :base module is an com.android.library only contains code and resources which are shared between other modules. Reusing this way resources, layouts, views, and components in the different modules, without the need to duplicate code.

Data module

The :data module is an com.android.library for serving network requests or accessing to the database. Providing the data source for the many features that require it.

Domain module

The :domain module is an com.android.library lays a bridge between data and view layers. It performs any business logic getting data from data module and serves to view.

Test shared module

The :test-shared module is an com.android.library, basically contains test utilities that can be used by the different modules.

Architecture components

Ideally, ViewModels shouldn’t know anything about Android. This improves testability, leak safety and modularity. ViewModels have different scopes than activities or fragments. While a ViewModel is alive and running, an activity can be in any of its lifecycle states. Activities and fragments can be destroyed and created again while the ViewModel is unaware.

Passing a reference of the View (activity or fragment) to the ViewModel is a serious risk. Lets assume the ViewModel requests data from the network and the data comes back some time later. At that moment, the View reference might be destroyed or might be an old activity that is no longer visible, generating a memory leak and, possibly, a crash.

The communication between the different layers follow the above diagram using the reactive paradigm, observing changes on components without need of callbacks avoiding leaks and edge cases related with them.

Documentation

The documentation is generated following KDoc language (the equivalent of Java's JavaDoc) via documentation engine for Kotlin Dokka.

To consult it check this link or open the project /docs directory.

Tech-stack

This project takes advantage of many popular libraries, plugins and tools of the Android ecosystem. Most of the libraries are in the stable version, unless there is a good reason to use non-stable dependency.

Mainly on:

• Kotlin - Kotlin is a cross-platform, statically typed, general-purpose programming language with type inference.
• Kotlin DSL - Basically, a DSL is a language that focuses on just one particular part of an application. A general-purpose language, such as Kotlin or Java, on the other hand, can be used in multiple parts of one application.

Patterns

• Repository Pattern - The Repository Pattern is one of the most popular patterns to create an enterprise level application. It restricts us to work directly with the data in the application and creates new layers for database operations, business logic, and the application's UI.
• Observer Pattern - The observer pattern is a software design pattern in which an object, called the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes, usually by calling one of their methods.
• UseCase Pattern - This pattern means to convert and pass user actions to inner layers of the application.
• Delegation Pattern - In software engineering, the delegation pattern is an object-oriented design pattern that allows object composition to achieve the same code reuse as inheritance.
• TDD - Test-driven development (TDD) is a software development process that relies on the repetition of a very short development cycle: requirements are turned into very specific test cases, then the software is improved so that the tests pass.

Dependencies

• Jetpack:
  • Android KTX - provide concise, idiomatic Kotlin to Jetpack and Android platform APIs.
  • AndroidX - major improvement to the original Android Support Library, which is no longer maintained.
  • Data Binding - allows you to bind UI components in your layouts to data sources in your app using a declarative format rather than programmatically.
  • Lifecycle - perform actions in response to a change in the lifecycle status of another component, such as activities and fragments.
  • LiveData - lifecycle-aware, meaning it respects the lifecycle of other app components, such as activities, fragments, or services.
  • ViewModel - designed to store and manage UI-related data in a lifecycle conscious way. The ViewModel class allows data to survive configuration changes such as screen rotations.
• Coroutines - managing background threads with simplified code and reducing needs for callbacks.
• Dagger2 - dependency injector for replacement all FactoryFactory classes.
• Retrofit2 - type-safe HTTP client.
• Glide - image loading library for Android.
• Gson - makes it easy to parse JSON into Kotlin objects.
• Timber - a logger with a small, extensible API which provides utility on top of Android's normal Log class.
• and more...

Test dependencies

• Espresso - to write concise, beautiful, and reliable Android UI tests
• JUnit - a simple framework to write repeatable tests. It is an instance of the xUnit architecture for unit testing frameworks.
• Mockito - most popular Mocking framework for unit tests written in Java.
• Mockk - provides DSL to mock behavior. Built from zero to fit Kotlin language.
• AndroidX - the androidx test library provides an extensive framework for testing Android apps.
• and more...

Plugins

• Ktlint - an anti-bikeshedding Kotlin linter with built-in formatter.
• Detekt - a static code analysis tool for the Kotlin programming language.
• Spotless - a code formatter can do more than just find formatting errors.
• Versions - make easy to determine which dependencies have updates.
• Jacoco - code coverage library
• and more...

Resources

Projects

This is project is a sample, to inspire you and should handle most of the common cases, but obviously not all. If you need to take a look at additional resources to find solutions for your project, visit these interesting projects:

• iosched (by google) - official Android application from google IO 2019.
• plaid (by android) - app which provides design news & inspiration, being an example of implementing material design.
• sunflower (by android) - a gardening app illustrating Android development best practices with Android Jetpack.
• architecture-components-samples (by android) - collection of samples for Android Architecture Components.
• architecture-sample (by android) - collection of samples to discuss and showcase different architectural tools and patterns for Android apps.
• android-clean-architecture-boilerplate (by bufferapp) - an android boilerplate project using clean architecture
• android-kotlin-clean-architecture (by sanogueralorenzo) - android sample Clean Architecture app written in Kotlin.
• modularization-example (by JeroenMols) - easy to understand real-life example of a modularized Android app.
• lego-catalog (by Eli-Fox) - app illustrating current Android Architecture state using Android development best practices.
• tivi (by chrisbanes) - an app which attempts to use the latest cutting edge libraries and tools.
• android-showcase (by igorwojda) - app following best practices: Kotlin, coroutines, Clean Architecture, feature modules, tests, MVVM, static analysis.

Articles

A collection of very interesting articles related last android community tendencies and recommendations for start to take in consideration for your current/next project:

• Transform monolith to modularization application
• Using the Navigation Component in a Modular World
• Dependency injection in a multi module project
• ViewModels and LiveData: Patterns + AntiPatterns
• Dynamic feature and regular modules using Dagger2
• Android Architecture starring Kotlin Coroutines, Jetpack (MVVM, Room, Paging), Retrofit and Dagger 2
• Official Kotlin Style Guide with Ktlint
• Gradle dependency management with Kotlin (buildSrc)
• Detecting Kotlin Code Smells with Detekt
• Best coding practices, tips and more for Android

Libraries

The open-source community create and maintains tons of awesome libraries making your job more easy, giving the opportunity to use them in your developments. Here are a very important collection of them:

• awesome-android-ui - collection list of awesome Android UI/UX libraries.
• awesome-android-libraries - collection of awesome Kotlin related stuff.
• android-arsenal - android developer portal with tools, libraries, and apps.

Best practices

Avoid reinventing the wheel by following these guidelines:

• Google best practices
• Android development best practices

Codelabs

Google Developers Codelabs provide a guided, tutorial, hands-on coding experience. Most codelabs will step you through the process of building a small application, or adding a new feature to an existing application. They cover a wide range of android concepts to learn and practice:

• Android Developer Fundamentals
• Android Developer Codelabs

Contributions

All contributions are welcome! Please feel free to post questions, recommendations, ideas, bugs by create new issue following the template or if you want create directly new pull request.

Roadmap:

• [ ] - A detail screen to be added
• [ ] - Cards to have more detail
• [x] - Some screenshots to be added
• [x] - Write common DSL scripts

License

Copyright 2019 nuhkoca.com

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.