An android boilerplate project using clean architecture

Overview

Build Status codecov Codacy Badge

Android Clean Architecture Boilerplate

Welcome 👋 We hope this boilerplate is not only helpful to other developers, but also that it helps to educate in the area of architecture. We created this boilerplate for a few reasons:

  1. To experiment with modularisation
  2. To share some approaches to clean architecture, especially as we've been talking a lot about it
  3. To use as a starting point in future projects where clean architecture feels appropriate

It is written 100% in Kotlin with both UI and Unit tests - we will also be keeping this up-to-date as libraries change!

Disclaimer

Note: The use of clean architecture may seem over-complicated for this sample project. However, this allows us to keep the amount of boilerplate code to a minimum and also demonstrate the approach in a simpler form.

Clean Architecture will not be appropriate for every project, so it is down to you to decide whether or not it fits your needs 🙂

Languages, libraries and tools used

Requirements

Architecture

The architecture of the project follows the principles of Clean Architecture. Here's how the sample project implements it:

architecture

The sample app when run will show you a simple list of all the Bufferoos (Buffer team members!).

Drawing

Let's look at each of the architecture layers and the role each one plays :)

architecture

User Interface

This layer makes use of the Android Framework and is used to create all of our UI components to display inside of the Browse Activity. The layer receives its data from the Presentation layer and when retrieved, the received models are mapped using the Bufferoo Mapper so that the model can be mapped to this layer's interpretation of the Bufferoo instance, which is the BufferooViewModel. The Activity makes use of the BrowseContract to enable communication to and from the presenter.

Presentation

This layer's responsibility is to handle the presentation of the User Interface, but at the same time knows nothing about the user interface itself. This layer has no dependence on the Android Framework, it is a pure Kotlin module. Each Presenter class that is created implements the Presenter interface defined within an instance of a contract - in this case the BrowseContract, which also contains an interface for the View interface.

When a Presenter is constructed, an instance of this View is passed in. This view is then used and the presenter is set for it using the implemented setPresenter() call.

The presenters use an instance of a SingleUseCase from the Domain layer to retrieve data. Note here that there is no direct name reference to the UseCase that we are using - we do inject an instance of the GetBufferoos UseCase, however.

The presenter receives data from the Domain layer in the form of a Bufferoo. These instances are mapped to instance of this layers model, which is a BufferooView using the BufferooMapper.

Domain

The domain layer responsibility is to simply contain the UseCase instance used to retrieve data from the Data layer and pass it onto the Presentation layer. In our case, we define a GetBufferoos - this use case handles the subscribing and observing of our request for data from the BufferooRepository interface. This UseCase extends the SingleUseCase base class - therefore we can reference it from outer layers and avoid a direct reference to a specific implementation.

The layer defines the Bufferoo class but no mapper. This is because the Domain layer is our central layer, it knows nothing of the layers outside of it so has no need to map data to any other type of model.

The Domain layer defines the BufferooRepository interface which provides a set of methods for an external layer to implement as the UseCase classes use the interface when requesting data.

architecture

Data

The Data layer is our access point to external data layers and is used to fetch data from multiple sources (the cache and network in our case). It contains an implementation of the BufferooRepository, which is the BufferooDataRepository. To begin with, this class uses the BufferooDataStoreFactory to decide which data store class will be used when fetching data - this will be either the BufferooRemoteDataStore or the BufferooCacheDataStore - both of these classes implement the BufferooDataStore repository so that our DataStore classes are enforced.

Each of these DataStore classes also references a corresponding BufferooCache and BufferooRemote interface, which is used when requesting data from an external data source module.

This layers data model is the BufferooEntity. Here the BufferooMapper is used to map data to and from a Bufferoo instance from the domain layer and BufferooEntity instance from this layer as required.

Remote

The Remote layer handles all communications with remote sources, in our case it makes a simple API call using a Retrofit interface. The BufferooRemoteImpl class implements the BufferooRemote interface from the Data layer and uses the BufferooService to retrieve data from the API.

The API returns us instances of a BufferooModel and these are mapped to BufferooEntity instance from the Data layer using the BufferooEntityMapper class.

Cache

The Cache layer handles all communication with the local database which is used to cache data.

The data model for this layer is the CachedBufferoo and this is mapped to and from a BufferooEntity instance from the Data layer using the BufferooEntityMapper class.

Conclusion

We will be happy to answer any questions that you may have on this approach, and if you want to lend a hand with the boilerplate then please feel free to submit an issue and/or pull request 🙂

Again to note, use Clean Architecture where appropriate. This is example can appear as over-architectured for what it is - but it is an example only. The same can be said for individual models for each layer, this decision is down to you. In this example, the data used for every model is exactly the same, so some may argue that "hey, maybe we don't need to map between the presentation and user-interface layer". Or maybe you don't want to modularise your data layer into data/remote/cache and want to just have it in a single 'data' module. That decision is down to you and the project that you are working on 🙌🏻

Thanks

A special thanks to the authors involved with these two repositories, they were a great resource during our learning!

Comments
  • DataStore question

    DataStore question

    Hi, i have a question. Why did you introduce DataStore classes, instead of using DataSource itself?

    What is the gain of adding one more abstraction, DataSource is already interface and Repository would not be depended on Implementation any way?

    opened by jemshit 8
  • Architecture question

    Architecture question

    According to this talk : https://www.youtube.com/watch?v=Nsjsiz2A9mg Uncle bob says that a project's structure should not be MVC or MVP, MVVM..., But this project top structure is mobile-ui/presentation/domain/data..., Programmers cannot know what is this app doing at first glimpse, could you tell me what do you think about this? I am so confused. Thank you!!

    opened by hungyanbin 5
  • Question about some strange classes...

    Question about some strange classes...

    opened by urosjarc 4
  • [QUESTION] How to use this boilerplate properly?

    [QUESTION] How to use this boilerplate properly?

    Thank you for creating this awesome project and the lovely documentation and art!

    I am worried about the best way to include or start a derived professional app using AL 2.0.

    I know the licenses are compatible, but I would like to do it correctly and don't delete the docs.

    So new developers that continue the project understand the architecture easily and check changes.

    I want to avoid starting from scratch, so I would like to:

    • Move the license.txt and readme.md to a documentation folder and link to it from the new one.
    • Rename packages.
    • Include the buffer sample temporarily until I finish my tested alternative.
    • Delete buffer*-related code.
    • Create proper credits to Buffer in documentation folder or a better and recommended place.

    I am going to use this project in my personal apps, but I am worried about apps for clients.

    I am planning to contribute so guidelines about style and this topic would be appreciated.

    opened by albodelu 2
  • Fix travis build for api version 26

    Fix travis build for api version 26

    opened by ShikherVerma 1
  • LastCacheTime will be updated even if data is accessed from CacheDataStore?

    LastCacheTime will be updated even if data is accessed from CacheDataStore?

    https://github.com/bufferapp/android-clean-architecture-boilerplate/blob/f036554fcd5c43bd518a1a4c242d5406cbe681af/data/src/main/java/org/buffer/android/boilerplate/data/BufferooDataRepository.kt#L31

    I think there is some problem here. If I understand it correctly when the factory.retrieveDataStore() returns the BufferooCacheDataStore then this code is just taking the data from the cache and again storing it in the cache and updating LastCacheTime.

    This does not feel right. Is this intended behavior or some sort of issue?

    opened by jdsingh 1
  • Updated following libraries to latest version:

    Updated following libraries to latest version:

    • rxKotlin to 2.10
    • gson to 2.8.1
    • okhttp to 3.8.1
    • retrofit to 2.3.0
    • supportLibarary to 26.0.1
    • roboelectric to 3.4.2
    • asserj to 3.8.0
    • espresso to 3.0.0
    • testRunner to 1.0.0
    • gradle to 4.1

    Replaced dexmaker with MockitoAndroid reference: https://jeroenmols.com/blog/2017/01/17/mockitoandroid/

    Removed following warnings:

    • 'kapt.generateStubs' is not used by the 'kotlin-kapt' plugin
    • Configuration 'provided' in project ':mobile-ui' is deprecated. Use 'compileOnly' instead.
    • Configuration 'compile' in project ':mobile-ui' is deprecated. Use 'implementation' instead.
    opened by ravidsrk 1
  • Dependency management using Kotlin and buildSrc

    Dependency management using Kotlin and buildSrc

    Dependency management using Kotlin and buildSrc that enables autocomplete in build.gradle file and easy navigation to dependencies using Android studio

    opened by adityaladwa 0
  • Clean up dependencies.gradle

    Clean up dependencies.gradle

    It seems like there is no need to add jcenter to the repositories here? In build.gradle it is added anyway, alongside the google one:

    allprojects {
        repositories {
            google()
            jcenter()
        }
    }
    
    opened by grepx 0
  • Refreshing Coroutines,Flow, KMM,Compose

    Refreshing Coroutines,Flow, KMM,Compose

    Well, let's start with Coroutines instead of RXJava2. Hey joe I got a job with your Caster course on Clean Architecture, so I would like to give back, now that have two years and half real working experience, if someone is in to review the code I am all in to contribute to your project, as I read on twitter you want to give it but do not have time to work on that.

    opened by Ndrocchietto 0
  • Where do WorkManager, JobScheduler Fit?

    Where do WorkManager, JobScheduler Fit?

    Usually, in apps, there are some tasks that we run in the background, such as syncing of data, analytics etc. Google suggested to use deferrable components such as WorkManager and JobScheduler in such instances. Where do these components fit in Clean Architecture?

    opened by KwabenBerko 2
  • Will the presentation models always be useless?

    Will the presentation models always be useless?

    Hello there. I was thinking after seeing a lot of repositories that usually the presenter or viewModel maps the domain models to presentation (there are no UI models) but this has a lot of problems (I shouldn't reference any platform resource, jetpack compose, etc). Even thinking in multiplatform this can be a huge problem.

    Then I found this repo where I can see that the UI is separated from presentation so this problem is solved. But then I thought that really the presentation models will be the same than domain models.

    Why should I keep the presentation models instead of using domain models directly until I reach the UI layer?

    opened by JavierSegoviaCordoba 2
  • Where should the data model for sending between activity/fragment stay.

    Where should the data model for sending between activity/fragment stay.

    I have a question the data model that are using for sending between activity/fragment live?

    the data model most likely domain's data model but it's can be serialized/Parcelized

    opened by arohim 2
Owner
Buffer
Helping people build their business on social media since 2011
Buffer
A fork of our clean architecture boilerplate using the Model-View-Intent pattern

Android Clean Architecture MVI Boilerplate Note: This is a fork of our original Clean Architecture Boilerplate, except in this repo we have switched o

Buffer 963 Sep 16, 2022
Skeleton project for show the architecture of Android project using MVVM, Clean Architecture and Kotlin coroutine Flow

ClearScoreDemo Skeleton project for showing the architecture of Android project using MVVM, Clean architecture and Kotlin coroutine Flow App Architect

Plabon Modak 1 Mar 6, 2022
Android-Boilerplate - Base project for android development with new technology

Android-Boilerplate Base project for android development with new technology, in

Muhammad Rizky Arifin 1 Aug 15, 2022
An Android template project (in Kotlin) with boilerplate and current patterns.

android-starter-v4 An Android template project (in Kotlin) with boilerplate and plumbing, exploring current architecture patterns. A bit too much for

Matthias Urhahn 12 Sep 26, 2022
FaceTimeClone app that implements Coroutines , mvvm architecture , clean architecture , navigation component , hilt , etc.... using kotlin language

This repository contains a FaceTimeClone app that implements Coroutines , mvvm architecture , clean architecture , navigation component , hilt , etc.... using kotlin language

null 14 Aug 16, 2022
Android Clean Architecture in Rorty is a sample project that presents modern, approach to Android application development using Kotlin and latest tech-stack.

Android Clean Architecture in Rorty is a sample project that presents modern, approach to Android application development using Kotlin and latest tech-stack.

Mr.Sanchez 156 Sep 26, 2022
A personal project made using Jetpack Compose, Clean-MVVM architecture and other jetpack libraries

A basic CRUD for recording your personal credit and debit transactions. Made using Jetpack Compose, Clean-MVVM and other Jetpack libraries, incorporated with Unit Tests.

Shoaib Ahmed 2 Jul 23, 2022
A Kotlin library for reactive and boilerplate-free SharedPreferences in Android

KPreferences A Kotlin library for reactive and boilerplate-free Shared Preferences in Android. With KPreferences you can use Kotlin's marvelous delega

Mohamad Amin Mohamadi 19 Dec 16, 2020
👋 A common toolkit (utils) ⚒️ built to help you further reduce Kotlin boilerplate code and improve development efficiency. Do you think 'kotlin-stdlib' or 'android-ktx' is not sweet enough? You need this! 🍭

Toolkit [ ?? Work in progress ⛏ ?? ??️ ?? ] Snapshot version: repositories { maven("https://s01.oss.sonatype.org/content/repositories/snapshots") }

凛 35 Jul 23, 2022
Cleanarchitecture MVVM Hilt base - Android Clean Architecture example project

Android Clean Architecture example project Note: This is project based on MVVM c

Mohsin Javed 4 Aug 30, 2022
A sample project demonstrating clean architecture in an Android app

Android Clean Architecture Sample A sample project demonstrating clean architecture in an Android app Tech stack Kotlin Coroutines Flow Jetpack App St

null 19 Aug 28, 2022
Practice Project with Clean architecture(offline +online)

Dictionary-App Basically this project will save what you search once in dictionary and then if you will search the same word again in search when ther

Farooq Ahmad 3 Aug 16, 2022
Android News app developed using Clean + MVVM architecture

Clean-MVVM-NewsApp An Android application built using Clean + MVVM architecture. Featured in Components used in the app. Kotlin - As a programming lan

Naveen T P 52 Jun 17, 2022
Android application showcasing the MVVM architecture, Clean code using Kotlin, Coroutine, Flow and databinding.

Code4Lyst Android application showcasing the MVVM architecture, Clean code using Kotlin, Coroutine, Flow and databinding. App Architecture MVVM CleanC

Plabon Modak 1 Nov 29, 2021
🚀 Sample Android Clean Architecture on JetRorty App focused on the scalability, testability and maintainability written in Kotlin, following best practices using Jetpack with Compose.

Android Clean Architecture in Rorty is a sample project that presents modern, approach to Android application development using Kotlin and latest tech-stack.

Mr.Sanchez 81 Sep 24, 2022
Sample Android Clean Architecture on App focused on written in Kotlin, following best practices using Jetpack with Compose.

Rick And Morty Jetpack Compose Sample App Table of Contents About the Project Architecture Features Environment Setup Contact About The Project This S

Mert Toptas 121 Sep 21, 2022
Note taking app using SOLID principles and CLEAN architecture patterns. Uses Room database, MVVM, Use cases

ShoppingNotes Note taking app using SOLID principles and CLEAN architecture patt

Chris Athanas 1 Dec 27, 2021
RoomJetpackCompose is an app written in Kotlin and shows a simple solution to perform CRUD operations in the Room database using Kotlin Flow in clean architecture.

RoomJetpackCompose is an app written in Kotlin and shows a simple solution to perform CRUD operations in the Room database using Kotlin Flow in clean architecture.

Alex 13 Sep 24, 2022