Building Scalable Navigation System in Android
Navigation sounds like a trivial problem to solve right? as you start an activity or a fragment and the flow goes on. But Let’s be real that is not how it works. Usually, you will have a ton of conditional navigation like, is that user is logged in? is that his/her first time should I open home? or should I open the onboarding flow? How many screens can I trigger the auth flow from?
mmmm No problem I can deal with that here is my superpower static navigator class ✨ Or no I won’t make it static so the DI folks don’t judge me. We are scaling and the team is growing. Ok, let’s introduce feature per module. 😕 Oh, we are in the age of on-demand services. Let’s add product flavors. Don’t worry we will reuse the auth flow to work for the rider and driver app (extra😕😕😕)
The APK size is huge what are you doing? mmm I think my dagger injected navigator class won’t work anymore should I use Koin? And much more wondering why our app gets complicated. So let’s fix that!
Where are we?
Sorry for the long intro but I need to address a real pain that happens to most of us on a daily basis. I want to talk about how we handle navigation in our app. A multi favored app with 3 flavors and more in the future. with multi modules. Activity/Feature per module, navigation library, dagger, And all the goodies. Sounds Like a fun place to work at. (It’s if you asked me 🤭)
What do we want to achieve?
While architecting our navigation system we want to achieve some goals.
- Reuse Fragments in different flows/modules.
- Make the fragments agnostic from the flow that they appear in.
- Passing different domain logic implementation in different flows to the same fragment.
- Reuse flows in different apps (product flavors).
- Every feature module doesn’t know anything or have a dependency on any other feature modules.
- Stay away from field injection in fragment and all the dagger drama nonsense.
- Testing the fragment in isolation from its parent or host.
Code
All of the sample code will be in that GitHub repository. If you want to jump into the source code directly.
Coordinators
We opted to use the coordinator design pattern. We are heavily influenced by this amazing article by Monzo and this article by Hannes Dorfmann. I highly suggest everyone read those articles before continuing to this one.
The TL;DR for who doesn’t know the coordinator pattern is the following quote from Monzo's article.
The basic idea of the pattern is that you have a class that lives on a level above each individual screen, and ‘coordinates’ the navigation between these screens within a particular flow (i.e. you have on ‘Coordinator’ for each flow). The Coordinator also hosts all flow-specific logic, making individual screens agnostic to the flow they appear in.
So we use the coordinator to construct a flow. A flow is a set of fragments/custom views. In our case, the fragments might be in the same module or come from another module. Why they are not all in one feature module? a great question in our case we have some app-specific fragments like the home screen for the app and it can open other fragments from other feature modules.
Here is a real use case that makes the coordinator pattern really shine. Let’s assume we have a ProfileFragment and it’s used in two flows the auth flow and setting flow. like the diagram below.
Auth Flow: When the user signup we send him to the ProfileFragment to edit his data then click save we will send the data to the auth endpoints and the next destination will be the CreatePasswordFragment.
Setting Flow: When the user opens the app settings then go to edit his profile and click save we will send the data to the user endpoint and the next destination will be the home screen.
As you can see different flows, different domain logic but the same Fragment and ViewModel.🤩
Fragment
That’s how a simple fragment in our app looks like. Don’t judge me for the generics 😛. As you can see there is no injection in the fragment or any reference to other fragments or activities. Which was our intention from the beginning.
What we care about here is the hostedViewModel() property delegate and what happens when we click on search which should send us to another UI.
At first look, you say mmm what all of that complicated code. but I saw it before not sure where though. and you will be right it’s the same code in viewModels() in Jetpack with a minor difference, Some coordinator code. As you can see that code trying to access something called CoordinatorHost which is from the name just an interface that holds a reference to a coordinator typically implemented by the flow host which is the activity, in that case, we will see it in a bit. It can be a fragment also.👀 As you can see it ask the current coordinator to get the viewModelFactory for that screen. That approach has multiple benefits.
- We get our view model factory which contains all the dependencies that our view model needs to work from the coordinator, We can pass different factories with different implementation for a specific flow without the need to tell the fragment or the view model anything about it 😍
- There is no injection code or all the complicated dagger setup or hilt or anything just pure android code 🤭
- In a test, we can pass the mocked or fake implementation of the view model factory without any weird workaround. That will allow us to use the new FragmentScenario Easily.
CoordinatorHost
I will quote Monzo on it
CoordinatorHostis a class that contains aCoordinator. is in charge of constructing theCoordinator(or, if you use Dagger or some other DI framework, also provides any input to the flow into theCoordinator. The input is given as intent extras (for Activities) or in the arguments bundle (for Fragments). Then, the input is provided to the
As promised here is the CoordinatorHost it’s a very simple interface
interface CoordinatorHost<C : Coordinator> { val coordinator: C
}
Our flow host activity or fragment can implement it to create and manage the lifecycle of the coordinator.
Here is our activity simple and straight forward. If you want to see the magic that happens in the BaseActivity check that gist. As you can see the activity is also responsible for creating the dagger component and manage it to survive configuration change. And the code screaming with the navigation component 😁 We use navigation components for internal flow navigation between fragments. it’s very robust, make animation and deep linking easy. And the safe args plugin is just so good as we will see in the coordinator code.
Here is a simple view of our graph
ViewModel
So back to the fragment what it’s view model looks like and what happens to the search click?
Here is a simple version of the view model. As you can see when search clicked it call sendCoordinatorEvent a method which will just emit to an event live data and the coordinator will listen to it and depending on the current coordinator. It will handle the event according to the flow
protected fun <E : CoordinatorEvent> sendCoordinatorEvent(event: E){
_coordinatorEvent.value = Event(event)
}In the base fragment here how the coordinator will receive the events.
viewModel.coordinatorEvent.observe(viewLifecycleOwner, EventObserver {
getCoordinator().onEvent(it)
})private fun getCoordinator(): Coordinator {
return (requireActivity() as CoordinatorHost<*>).coordinator
}
Coordinator
We talked a lot about it but how it actually look 🙈 We made it similar to what Monzo did and here is ShoppingCoordinator for example.
As you can see here we inject the dependencies required for the flow. it cloud be some view model factories or use cases depending on the flow. As you can see in onCreateViewModelFactory we use the AbstractFactory Design pattern to create the factory because we want a new factory each time the fragment created to ensure there is no state from a previous flow contained. We use AssistedInject to do that and also to provide fragment arguments to the view models like id for example.
We use safe args plugin to generate the fragment required argument without the hassle of handling keys or type safety all done for use thanks to the plugin.
onEvent() Where the magic happens the coordinator will receive an event and it can go anywhere depending on the flow you can do your conditional navigation here. For example, some fragment send start event you can inject the user manager to the coordinator and check if the user is logged in or not and different cases lead to different destinations or maybe even a different flow 👀
We also inject our dependencies as Lazy and we get them on demand to avoid performance issues by loading all the dependencies at once.
onCreateViewModelFactory() Receives a Displayable which a contract interface implemented by the BaseFragment. Why we did that instead of just fragment? So if we have custom views in our flow we can provide them with their view model factories also by making the view implement displayable.
FeatureNavigator
As we said the coordinator can navigate to different flows. in our case, the flow is hosted inside activity but how it will achieve that and we set up a rule in being that every feature doesn’t know about other features so we can’t navigate via explicit intent. to no one surprise, we will use the FeatureNavigator It sounds like a fancy name but it’s a very simple interface that just knows about all the features in that app and it lives in the core module
interface FeatureNavigator { fun splash(): Intent fun rider(): Intent fun driver(): Intent fun shopping(credit: Float): Intent
}
So how the implementation looks like is the interesting part hear and actually it lives in core it doesn’t need to be in the app 👀👀.
class FeatureNavigatorImpl @Inject constructor(private val context: Context) : FeatureNavigator { override fun splash(): Intent {
return Actions.openSplashIntent(context)
} override fun rider(): Intent {
return Actions.openRiderIntent(context)
} override fun driver(): Intent {
return Actions.openDriverIntent(context)
} override fun shopping(credit: Float): Intent {
return Actions.openShoppingIntent(context, CreditArgs(credit))
}
}
Dude? is that the interesting part 😏 you are just calling other static class why you just call it in the coordinator. It’s very simple I want my coordinator to be free from android dependencies to make testing easy. Anyway, the interesting part actually is Actions class Let’s take a look at it
fun openShoppingIntent(context: Context, args: CreditArgs) =
internalIntent(context, "com.capiter.shopping.open")
.putExtra(CreditArgs.KEY, args)private fun internalIntent(context: Context, action: String) =
Intent(action).setPackage(context.packageName)
The idea here we are using implicit intents with intent action. This idea is inspired by this great article by Jeroen Mols, Then define the action in the activity in AndroidManifest and we are ready to go.
<activity
android:name=".presentation.view.ShoppingActivity">
<intent-filter>
<action android:name="com.capiter.shopping.open" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>Product Flavors
We treat flavors as Android modules and depending on current flavor we navigate to the flavor module. The idea of actions gives us very powerful capabilities since the feature navigator implementation doesn’t rely on a reference to the activity just rely on the action we can compile only the modules required for that flavor avoiding the need for compiling the whole thing and increase the APK size and also as a side effect that will speed our build times. When you work on the specific flavor you don’t need to compile the whole app every time and also when generating build APK.
Let’s talk a look at the app build.gradle
dependencies {
riderImplementation project(":rider")
driverImplementation project(":driver") implementation Dependencies.Kotlin.stdlib implementation Dependencies.AndroidX.ktx
implementation Dependencies.AndroidX.fragment
implementation Dependencies.AndroidX.appcompat
....
}
So how that will work? Our app just contains the SplashActivity and AppCoordinator which decides where to go if the user is logged in, go home otherwise go to auth. As you can see the logic of deciding that happens in the coordinator, The activity completely agnostic.
//Activity
postAction(SplashAction.Start)//ViewModel
sendCoordinatorEvent(AppCoordinatorEvent.Start)
Fragment Result
It’s a very common use case to start a fragment from another fragment and waiting for a result similar to startActivityForResult() For example, you are requesting a ride so you open the MapFragment, select drop pin then return the lat, lng to the RequestRideFragment. Another example you are in ProfileFragment and editing your phone number so you open the CountriesFragment to choose a country and send the result back (country) to the ProfileFragment ..etc so How to handle that? there are multiple solutions one of the common ones is to use a shared view model and scope it to parent activity using activityViewModels() but this solution violates one of the goals we set earlier. Each fragment should be agnostic from the flow that they appear in. And using the activity view model tight the fragment to a certain flow/module.
What we will use here is the new fragment result API introduced in the AndroidX fragment library version 1.3.0. Here is how it works. The fragment that needs the result will listen to it like the code snippet.
setFragmentResultListener(MapRequestKeys.MAP) { _, bundle ->
val location: Location? = bundle.getParcelable(MapRequestKeys.KEY_LOCATION)
if (location != null) {
postAction(ArrivedViewAction.DropPinLocation(location))
}
}Pretty straight forward. Just listen for a result for that request key. We have static keys so they can be shared in different fragments/flows.
object MapRequestKeys {
const val MAP = "request_key_map"
const val KEY_LOCATION = "key_location"
}In the MapFragment to set the result for example after a confirmation button.
setFragmentResult(
MapRequestKeys.MAP,
bundleOf(MapRequestKeys.KEY_LOCATION to viewEvent.location)
)That’s it! Very simple yet powerful and make out fragments agnostic.
Analytics
It’s really common on most apps to log some analytics data related to navigation to improve UX and A/B testing. For example from where the user opened the cart. from the cart icon on the home screen? or from the product detail? and it wasn’t that fun to handle because every time you start the cart you always send with argument or intent the start destination for it. With the coordinator you don’ need to do that any more because the coordinator knows the current and next destination so you can put your analytics calls in it and make the fragments/activities free from that logic.
Drawbacks
Of course, like everything in life, it’s not all shiny we have some drawbacks for the above architecture which is not a deal-breaker for most use cases.
- Complexity: as you can see we moved away from just
startActivity()to multiple classes and interactions between them and it will take some time to fully understand what’s going on. But the benefits we get is totally worth it because once you set it up and it clicks you will see a big smile in your face😃 - Boilerplate: when you saw how we inject the view model factories to the coordinator and provide it to the fragment. the first thing that comes in your mind what if we have 50 screens in one flow? that means I will have 50 constructor parameters and 50 conditions. The answer is yes and no. You should have small coordinators if it’s a big flow split it into small coordinators and combine them into one coordinator. In the end, a rule of thump your coordinator should have less than 7–8 screens in it. If more split it, that will increases readability and testability.
- Unhandled Coordinator Events: any view model can send coordinator events but it’s not guaranteed to be handled by the current coordinator. So a Fragment can ask to go to settings but the current coordinator doesn’t handle that the user will keep clicking and nothing happens. We don’t have a solution for that currently. UI testing and code review catch that but maybe a lint rule? We still exploring that area.
- FeatureNavigator: As you can see it knows about all the features in our app which is fine but what if we have 100 features? The interface and its implementation won’t be that great. We didn’t have this case yet but if we face it. We are thinking of making small feature navigators each one handles and responsible for a few sets of features and the
RootFeatureNavigatorwill know about these small feature navigators. Or You can just call theActionsdirectly in the coordinator and use power mock to verify invocation in testing but I’m not a big fan of that solution.
Conclusion
As you see (I used that word a lot😁) Building a scalable navigation system is not that hard with the right architecture you can change UX, do A/B testing, Reuse screens, and flows… etc. But that doesn’t mean you should add it right away in your project. Every project has different needs you should be aware of the benefits and drawbacks of the pattern. So you can take from it what will fit your app and make your life easier. We did what worked for us and made our development life easier and enjoyable. If you have other tips or opinions on how we can improve that share it with us in the comments.
Happy coding!
