Modular iOS Architecture @ Just Eat

The journey we took to restructure our mobile apps towards a modular architecture.

Overview

Modular mobile architectures have been a hot topic over the past 2 years, counting a plethora of articles and conference talks. Almost every big company promoted and discussed modularization publicly as a way to scale big projects. At Just Eat, we jumped on the modular architecture train probably before it was mainstream and, as we’ll discuss in this article, the root motivation was quite peculiar in the industry.
Over the years (2016-2019), we’ve completely revamped our iOS products from the ground up and learned a lot during this exciting and challenging journey. There is so much to say about the way we structured our iOS stack that it would probably deserve a series of articles, some of which have previously been posted. Here we summarize the high-level iOS architecture we crafted, covering the main aspects in a way concise enough for the reader to get a grasp of them and hopefully learn some valuable tips.

Modular Architecture

Lots of information can be found online on modular architectures. In short:

A modular architecture is a software design technique that emphasizes separating the functionality of a program into independent, interchangeable modules, such that each one contains everything necessary to execute only one aspect of the desired functionality.

Note that modular design applies to the code you own. A project with several third-party dependencies but no sensible separation for the code written by your team is not considered modular.
A modular design is more about the principle rather than the specific technology. One could achieve it in a variety of ways and with different tools. Here are some key points and examples that should inform the decision of the ifs and the hows of implementing modularization:

Business reasons

The company requires that parts of the codebase are reused and shared across projects, products, and teams;
The company requires multiple products to be unified into a single one.

Tech reasons

The codebase has grown to a state where things become harder and harder to maintain and to iterate over;
Development is slowed down due to multiple developers working on the same monolithic codebase;
Besides reusing code, you need to port functionalities across projects/products.

Multiple teams

The company structured teams following strategic models (e.g. Spotify model) and functional teams only work on a subset of the final product;
Ownership of small independent modules distributed across teams enables faster iterations;
The much smaller cognitive overhead of working on a smaller part of the whole product can vastly simplify the overall development.

Pre-existing knowledge

Members of the team might already be familiar with specific solutions (Carthage, CocoaPods, Swift Package Manager, manual frameworks setup within Xcode). In the case of a specific familiarity with a system, it’s recommended to start with it since all solutions come with pros and cons and there’s not a clear winner at the time of writing.

Modularizing code (if done sensibly) is almost always a good thing: it enforces separation of concerns, keeps complexity under control, allows faster development, etc. It has to be said that it’s not necessarily what one needs for small projects and its benefits become tangible only after a certain complexity threshold is crossed.

Journey to a new architecture

In 2014, Just Eat was a completely different environment from today and back then the business decided to split the tech department into separate departments: one for UK and one for the other countries. While this was done with the best intentions to allow faster evolution in the main market (UK), it quickly created a hard division between teams, services, and people. In less than 6 months, the UK and International APIs and consumer clients deeply diverged introducing country-specific logic and behaviors.
By mid-2016 the intent of “merging back” into a single global platform was internally announced and at that time it almost felt like a company acquisition. This is when we learned the importance of integrating people before technology.
The teams didn’t know each other very well and became reasonably territorial on their codebase. It didn’t help that the teams span multiple cities. It’s understandable that getting to an agreement on how going back to a single, global, and unified platform took months. The options we considered spanned from rewriting the product from scratch to picking one of the two existing ones and make it global. A complete rewrite would have eventually turned out to be a big-bang release with the risk of regressions being too high; not something sensible or safe to pursue. Picking one codebase over the other would have necessarily let down one of the two teams and caused the re-implementation of some missing features present in the other codebase. At that time, the UK project was in a better shape and new features were developed for the UK market first. The international project was a bit behind due to the extra complexity of supporting multiple countries and features being too market-specific.
During that time, the company was also undergoing massive growth and with multiple functional teams having been created internally, there was an increasing need to move towards modularization. Therefore, we decided to gradually and strategically modularize parts of the mobile products and onboard them onto the other codebase in a controlled and safe way. In doing so, we took the opportunity to deeply refactor and, in the vast majority of the cases, rewrite parts in their entirety enabling new designs, better tests, higher code coverage, and – holistically – a fully Swift codebase.
We knew that the best way to refactor and clean up the code was by following a bottom-up approach. We started with the foundations to solve small and well-defined problems – such as logging, tracking, theming – enabling the team to learn to think modular. We later moved to isolating big chunks of code into functional modules to be able to onboard them into the companion codebase and ship them on a phased rollout. We soon realized we needed a solid engine to handle run-time configurations and remote feature flagging to allow switching ON and OFF features as well as entire modules. As discussed in a previous article, we developed JustTweak to achieve this goal.
At the end of the journey, the UK and the International projects would look very similar, sharing a number of customizable modules, and differing only in the orchestration layer in the apps.
The Just Eat iOS apps are far bigger and more complex than they might look at first glance. Generically speaking, merging different codebases takes orders of magnitude longer than separating them, and for us, it was a process that took over 3 years, being possible thanks to unparalleled efforts of engineers brought to work together. Over this time, the whole team learned a lot, from the basics of developing code in isolation to how to scale a complex system.

Holistic Design 🤘

The following diagram outlines the modular architecture in its entirety as it is at the time of writing this article (December 2019). We can appreciate a fair number of modules clustered by type and the different consumer apps.

Whenever possible, we took the opportunity to abstract some modules having them in a state that allows open-sourcing the code. All of our open-source modules are licensed under Apache 2 and can be found at github.com/justeat.

Apps

Due to the history of Just Eat described above, we build different apps

per country
per brand
from different codebases

All the modularization work we did bottom-up brought us to a place where the apps differ only in the layer orchestrating the modules. With all the consumer-facing features been moved to the domain modules, there is very little code left in the apps.

Domain Modules

Domain modules contain features specific to an area of the product. As the diagram above shows, the sum of all those parts makes up the Just Eat apps. These modules are constantly modified and improved by our teams and updating the consumer apps to use newer versions is an explicit action. We don’t particularly care about backward compatibility here since we are the sole consumers and it’s common to break the public interface quite often if necessary. It might seem at first that domain modules should depend on some Core modules (e.g. APIClient) but doing so would complicate the dependency tree as we’ll discuss further in the “Dependency Management” section of this article. Instead, we inject core modules’ services, simply making them conformant to protocols defined in the domain module. In this way, we maintain a good abstraction and avoid tangling the dependency graph.

Core & Shared modules

The Core and Shared modules represent the foundations of our stack, things like:

custom UI framework
theming engine
logging, tracking, and analytics libraries
test utilities
client for all the Just Eat APIs
feature flagging and experimentation engine

and so forth. These modules – which are sometimes also made open-source – should not change frequently due to their nature. Here backward compatibility is important and we deprecate old APIs when introducing new ones. Both apps and domain modules can have shared modules as dependencies, while core modules can only be used by the apps. Updating the backbone of a system requires the propagation of the changes up in the stack (with its maintenance costs) and for this reason, we try to keep the number of shared modules very limited.

Structure of a module

As we touched on in previous articles, one of our fundamental principles is “always strive to find solutions to problems that are scalable and hide complexity as much as possible“. We are almost obsessed with making things as simple as they can be.
When building a module, our root principle is:

Every module should be well tested, maintainable, readable, easily pluggable, and reasonably documented.

The order of the adjectives implies some sort of priority.
First of all, the code must be unit tested, and in the case of domain modules, UI tests are required too. Without reasonable code coverage, no code is shipped to production. This is the first step to code maintainability, where maintainable code is intended as “code that is easy to modify or extend”. Readability is down to reasonable design, naming convention, coding standards, formatting, and all that jazz.
Every module exposes a Facade that is very succinct, usually no more than 200 lines long. This entry point is what makes a module easily pluggable. In our module blueprint, the bare minimum is a combination of a facade class, injected dependencies, and one or more configuration objects driving the behavior of the module (leveraging the underlying feature flagging system powered by JustTweak discussed in a previous article).
The facade should be all a developer needs to know in order to consume a module without having to look at implementation details. Just to give you an idea, here is an excerpt from the generated public interface of the Account module (not including the protocols):

public typealias PasswordManagementService = ForgottenPasswordServiceProtocol & ResetPasswordServiceProtocol
public typealias AuthenticationService = LoginServiceProtocol & SignUpServiceProtocol & PasswordManagementService & RecaptchaServiceProtocol
public typealias UserAccountService = AccountInfoServiceProtocol & ChangePasswordServiceProtocol & ForgottenPasswordServiceProtocol & AccountCreditServiceProtocol
public class AccountModule {
    public init(settings: Settings,
                authenticationService: AuthenticationService,
                userAccountService: UserAccountService,
                socialLoginServices: [SocialLoginService],
                userInfoProvider: UserInfoProvider) 
    public func startLogin(on viewController: UIViewController) -> FlowCoordinator
    public func startResetPassword(on viewController: UIViewController, token: Token) -> FlowCoordinator
    public func startAccountInfo(on navigationController: UINavigationController) -> FlowCoordinator
    public func startAccountCredit(on navigationController: UINavigationController) -> FlowCoordinator
    public func loginUsingSharedWebCredentials(handler: @escaping (LoginResult) -> Void)
}

We believe code should be self-descriptive and we tend to put comments only on code that really deserves some explanation, very much embracing John Ousterhout’s approach described in A Philosophy of Software Design. Documentation is mainly relegated to the README file and we treat every module as if it was an open-source project: the first thing consumers would look at is the README file, and so we make it as descriptive as possible.

Overall design

We generate all our modules using CocoaPods via $ pod lib create which creates the project with a standard template generating the Podfile, podspec, and demo app in a breeze. The podspec could specify additional dependencies (both third-party and Core modules) that the demo app’s Podfile could specify core modules dependencies alongside the module itself which is treated as a development pod as per standard setup.
The backbone of the module, which is the framework itself, encompasses both business logic and UI meaning that both source and asset files are part of it. In this way, the demo apps are very much lightweight and only showcase module features that are implemented in the framework.
The following diagram should summarize it all.

Demo Apps

Every module comes with a demo app we give particular care to. Demo apps are treated as first-class citizens and the stakeholders are both engineers and product managers. They massively help to showcase the module features – especially those under development – vastly simplify collaboration across Engineering, Product, and Design, and force a good mock-based test-first approach.
Following is a SpringBoard page showing our demo apps, very useful to individually showcase all the functionalities implemented over time, some of which might not surface in the final product to all users. Some features are behind experiments, some still in development, while others might have been retired but still present in the modules.
Every demo app has a main menu to:

access the features
force a specific language
toggle configuration flags via JustTweak
customize mock data

We show the example of the Account module demo app on the right.

Internal design

It’s worth noting that our root principle mentioned above does not include any reference to the internal architecture of a module and this is intentional. It’s common for iOS teams in the industry to debate on which architecture to adopt across the entire codebase but the truth is that such debate aims to find an answer to a non-existing problem. With an increasing number of modules and engineers, it’s fundamentally impossible to align on a single paradigm shared and agreed upon by everyone. Betting on a single architectural design would ultimately let down some engineers who would complain down the road that a different design would have played out better.
We decided to stick with the following rule of thumb:

Developers are free to use the architectural design they feel would work better for a given problem.

This approach brought us to have a variety of different designs – spanning from simple old-school MVC, to a more evolved VIPER – and we constantly learn from each other’s code. What’s important at the end of the day is that techniques such as inversion of control, dependency injection, and more generally the SOLID principles, are used appropriately to embrace our root principle.

Dependency Management

We rely heavily on CocoaPods since we adopted it in the early days as it felt like the best and most mature choice at the time we started modularizing our codebase. We think this still holds at the time of writing this article but we can envision a shift to SPM (Swift Package Manager) in 1-2 years time.
With a growing number of modules, comes the responsibility of managing the dependencies between them. No panacea can cure dependency hell, but one should adopt some tricks to keep the complexity of the stack under reasonable control.
Here’s a summary of what worked for us:

Always respect semantic versioning;
Keep the dependency graph as shallow as possible. From our apps to the leaves of the graph there are no more than 2 levels;
Use a minimal amount of shared dependencies. Be aware that every extra level with shared modules brings in higher complexity;
Reduce the number of third-party libraries to the bare minimum. Code that’s not written and owned by your team is not under your control;
Never make modules within a group (domain, core, shared) depend on other modules of the same group;
Automate the publishing of new versions. When a pull request gets merged into the master branch, it must also contain a version change in the podspec. Our continuous integration system will automatically validate the podspec, publish it to our private spec repository, and in just a matter of minutes the new version becomes available;
Fix the version for dependencies in the Podfile. Whether it is a consumer app or a demo app, we want both our modules and third-party libraries not to be updated unintentionally. It’s acceptable to use the optimistic operator for third-party libraries to allow automatic updates of new patch versions;
Fix the version for third-party libraries in the modules’ podspec. This guarantees that modules’ behavior won’t change in the event of changes in external libraries. Failing to do so would allow defining different versions in the app’s Podfile, potentially causing the module to not function correctly or even to not compile;
Do not fix the version for shared modules in the modules’ podspec. In this way, we let the apps define the version in the Podfile, which is particularly useful for modules that change often, avoiding the hassle of updating the version of the shared modules in every podspec referencing it. If a new version of a shared module is not backward compatible with the module consuming it, the failure would be reported by the continuous integration system as soon as a new pull request gets raised.

A note on the Monorepo approach

When it comes to dependency management it would be unfair not to mention the opinable monorepo approach. Monorepos have been discussed quite a lot by the community to pose a remedy to dependency management (de facto ignoring it), some engineers praise them, others are quite contrary. Facebook, Google, and Uber are just some of the big companies known to have adopted this technique, but in hindsight, it’s still unclear if it was the best decision for them.
In our opinion, monorepos can sometimes be a good choice.
For example, in our case, a great benefit a monorepo would give us is the ability to prepare a single pull request for both implementing a code change in a module and integrating it into the apps. This will have an even greater impact when all the Just Eat consumer apps are globalized into a single codebase.

Onwards and upwards

Modularizing the iOS product has been a long journey and the learnings were immense. All in all, it took more than 3 years, from May 2016 to October 2019, always balancing tech and product improvements. Our natural next step is unifying the apps into a single global project, migrating the international countries over to the UK project to ultimately reach the utopian state of having a single global app. All the modules have been implemented in a fairly abstract way and following a white labeling approach, allowing us to extend support to new countries and onboard acquired companies in the easiest possible way.