Creating a Marvel Database app with Room and Retrofit — The Plan
This tutorial is the first of two parts. Part I is the planning process, and Part II will be the implementation. I’ll be showing how an app idea can be turned into a plan that you can work with.
The App
The app will be named “Marvel Database”. Its’ simple definition goes like this:
Access information on your favorite heroes and villains from the Marvel Universe!
It will collect information from the Marvel API and display it to the user. It will also keep bookmarks for the user to have quick access to. There’s nothing else to it. This is to keep the plan short and make the app simple.
The Plan
The Plan itself consists of 3 main parts:
- The Data Definition: the structure and the format of the data we’re going to use.
- The UX/Flow Diagram: the list of all screens and the possible UI/Interactions between all of them.
- The Architecture: how the code itself will be structured.
This is based on the Waterfall Model for software development, with each part roughly corresponding to the Systems Requirements, Analysis, and Design phases, respectively. I chose the Waterfall Model because it seems simple to work with when compared with other methodologies like Agile. I’ll be discussing how each part of the plan is made.
The Data
The structure and format of the data we’re using needs to be known, as it will affect the way we can deliver User Experience. We’re using only the Marvel APIs for the app, so all we need to know comes from their documentation. Here’s a brief overview:
For the format, Marvel uses JSON format, so we can use a parser like Gson on the data. As for the structure, Marvel objects fall into six main categories:
- Characters
- Creators
- Comics
- Stories
- Series
- Events
Information on each of these entities is quite large, and they also contain references to other entities in the form. In addition to these, there are also data wrappers, including wrappers for image URLs. Search functionality (with sort and filter) is supported for each category, but none for all or more than one of these categories. We’ll use this knowledge to define our entities, and this will also affect the way we design our app flow.
The UX/Flow Diagram
“When the user opens the app, what do they see on the main screen?”
“Do they see the information from Marvel all at once or go to a separate screen?”
“How will they view and manage their bookmarks?”
These are the kinds of questions we need to ask to establish a definite idea of how the user interacts with the app, and in turn how to model our Activities, Fragments, etc. Now that we have an idea of the data, we can use that to answer our questions.
Keep in mind that the term “Screen” as I use it refers to an Android Activity, along with its’ respective ViewModel, any Fragments it uses, and all related code.
From what we’ve learned about our data, since there are only six main categories, we can put all of them on the Home Screen, and let the user search from each category on a separate screen, — the Search Screen. The user can then view a list of results and check the details of a specific entity on a separate screen, — a Details Screen. As for the bookmarks, the user will be able to add them from both the Search Screen and the Details Screen and manage them on the Bookmarks Screen.
We have our screens, four in total, but we still need to know about the navigation from one screen to another. I’ll skip talking about it for brevity, and simply show the diagram based on what we know now:
The Architecture
We’ll be using Clean Architecture for this app. It separates code into various circles based on their level of abstraction. For the Android version of Clean Architecture, there are three circles and five levels in total, as shown in the graph, and I’ll cover each implementation in detail in no specific order.
The Presentation Layer
This layer contains all UI-related code and logic. It directly interacts with the user. Here is where the code for our screens will go. There are only four screens, but each screen may have a Fragment and will have a ViewModel associated with it. All other UI-related code including RecyclerView Adapters, ViewModel Factories, etc, will also go here.
The Framework Layer
This layer will contain everything that relates directly to the Android framework. In this case, our networking and database code are the only kinds of code that belong here. For networking, we’ll use one class for our API calls: MarvelApiClient. For our database, we only need to store bookmarks, so we’ll use a BookmarkEntity (which we’ll keep in the domain layer), and a BookmarkDao class, along with a MarvelRoomDb class.
The Data Layer
All data manipulation is done in this layer. A problem arises, though, because to manipulate data via network calls or database queries, this layer needs to communicate with the code in the Framework layer, which would violate the Dependency Rule of Clean Architecture, which states that all dependencies can only point inwards. In order to obey the Dependency Rule, and not let our classes in this layer directly communicate with the Framework layer, we’ll use a technique called Dependency Inversion, by defining abstractions in the Data layer for the Framework layer to implement. These abstractions in our case will be the DatabaseDataSourceand NetworkDataSourceinterfaces. We’ll use the repository pattern by adding one repository per screen.
The Use Case Layer
A use case is a possible interaction of the UI layer with the data layer. Examples of use cases that we can come up with include submitting the search query on the Search Screen and making bookmarks from the Details Screen. We can simply create one UseCase class per screen for all the use cases for that screen.
The Domain Layer
Here is where we keep our data models. Note that in true Clean Architecture, our data models should be kept in each layer, and our entities/business rules should be kept here, but for our case, we don’t have any business rules, since we’re purely consuming data, so we’ll stick to our variation.
After defining everything, we can come up with a diagram like this:
Conclusion
Using the Waterfall Model, we were able to come up with one for a simple Android app. Plans don’t have to be very complex, but you need to have one if you want to build apps. I hope I was able to show you the importance of plans, and also how you can go about your own plans.
Thank you for your time.
