Golden rule

Although Kotlin and Swift share many syntactic similarities, their underlying architectures are different. We must keep in mind that adoption will always be more challenging for iOS, and therefore, we should be empathetic to the challenges this team may face. We must embrace these challenges as our own and be committed to find the best solutions.

Starting point

One key discussion was whether to opt for a single-module or multi-module approach and how to structure it.

We chose a multi-module project structured by layers to ensure a clear separation of concerns across the UI, Domain (optional), and Data layers, which also highlights cross-platform similarities, enhancing collaboration and streamlining synchronised feature development across teams.

The next discussion was about which layers would be shared. For example, should it be the Data Layer along with the UI Layer (state holders) or just the Data Layer? And which components within these layers — network, database, managers (repositories), models, view models, etc.?

We chose to focus on sharing only the Data Layer. Perhaps the most commonly adopted approach and you’ll understand why.

Finally, we decided to adopt a monorepo approach due to the team’s size, code governance, and the project’s complexity.

Architecture

By choosing to share only the Data Layer, it means that each platform will be fully responsible for implementing the UI and Domain Layers.

Although the Domain Layer could be optional, I will later explore the benefits of creating a lightweight Data Layer on iOS to align with the shared module’s Data Layer, where the Domain Layer will play an important role.

Shared code

The Data Layer of the applications will reside here, in the shared module. This is where we define our models, data providers (both local and remote) and data managers, which orchestrate these components.

Each platform consumes this module just like they would with any other external dependency.

Duplicated code

The UI and Domain Layers of each application will reside within their respective modules. I’ll focus on the iOS implementation, and this will be its structure:

Shared code

Based on our decisions, the shared module will also follow a gradle multi-module architecture. The modules data-models, core-database, and core-network are independent, while data-managers depends on all three. Each module is responsible for providing its own Dependency Injection (DI) logic, but the core-di module manages the root DI system, utilised by all platforms. This is why the core-di module depends on all other modules and will also contain the Objective-C framework settings.

These five modules constitute the Data Layer.

Facade

It is important to ensure that the artefact each platform will consume is as optimised as possible in terms of size and content. To achieve this, there are several best practices available for this task. The CardsManager class implements the Facade design pattern to encapsulate and protect access to the internal core-database and core-network modules.

Visibility Modifiers

We should leverage the internal modifier to ensure that functions, properties, classes, objects, and interfaces are only visible within the same module. In some cases, we may need to use the public modifier to make elements accessible to other Kotlin modules, but iOS doesn’t necessarily need access to them. To exclude these from the iOS compilation, we can use the @HiddenFromObjC annotation which prevents a function or property from being exported.

Framework settings

Given that we’ve opted for a multi-module architecture with interdependencies between the modules, it’s crucial to apply specific techniques to ensure the final binary preserves these relationships in a readable manner. Currently, KMP has a limitation where each binary framework is compiled as a “closed world”. As a result, it’s impossible to pass custom types between two frameworks, even if they are identical in Kotlin.

Let’s say I have two modules, shared and shared-models, each providing their own binary frameworks: Shared and SharedModels, respectively. The shared-models contains a data class Hello, and the shared module depends on shared-models with a public method that takes Hello as a parameter. When these modules are exported to Swift, we observe the following:

Instead of:

This means that the Shared framework includes all external dependencies from SharedModel and generates new types to reference those external types. As a result, we end up having Shared_modelsHello instead of just Hello.

To address this limitation we need to bundle not only the classes from the current project but also the classes from its dependencies. To specify which dependencies to export to a binary, we use the export method. This ensures that the external types from dependent modules are correctly referenced, avoiding the duplication of types:

This solution is known as an umbrella framework. It prevents the iOS app from bloating with duplicated dependencies, optimises the resulting artefact, and eliminates frustrations caused by dependency incompatibilities. Additionally, the Facade pattern plays a crucial role by preventing certain code from being exported to the final binary. This is particularly beneficial for the core-database module, which relies on SQLDelight to generate all database access code.

note: using export will also assist us with other tasks, I’ll elaborate on this as it becomes relevant in the following sections.

Koin

Koin is being used to manage DI in the project. As mentioned, core-di module unique responsibility is to manage the root DI system, utilised by all platforms, centralising its configuration and initialisation:

By delegating each module the responsibility of providing its own DI setup through a public function — such as networkDiModule, databaseDiModule, and managersDiModule — we achieve a more lightweight Koin configuration. This approach allows us to access the DI of a specific module without needing to rely on the core-di module, which is particularly advantageous for testing scenarios where only certain dependencies are required.

The previously mentioned framework technique of using export is also crucial for maintaining consistency between external types from dependent modules that will be used in iOS:

Tests

When structuring our team, we can adopt a horizontal approach, where one team works on the shared module and another on the platforms, or we can take a vertical approach, where each team works on a feature from the shared module through to the platforms. Regardless of the chosen approach, it is imperative that the shared module is as thoroughly covered with (useful) tests as possible.

As mentioned, each module is responsible for providing its own DI setup. Therefore, to test the core-database module, inside commonTest, I have the following:

Which will be used:

If I want to test my data-managers module, specifically the CardsManager class, one of its properties is a MagicDao instance. Although the data-managers module depends on the core-database module, we don’t have access to its commonTest folder, which prevents me from using the databaseDiTestModule() method in commonTest from data-managers. To work around this current limitation, I will replicate its initialisation in the commonMain folder, and as a result:

With this approach, modules that depend on core-database can use databaseDiTestModule() and retrieve its test instance for use in theirs commonTest folders:

Kotlin & Swift interoperability

Since Kotlin primarily generates Objective-C code, Swift’s calls to Kotlin through Objective-C, can result in loss of critical Kotlin language features, such as:

• Enums
• Sealed classes
• Coroutines (concurrency)
• Default args
• Generics

André Oriani wrote an excellent series of articles on this topic. Additionally, the Kotlin-Swift interopedia guide is also a valuable resource.

Focusing on Coroutines, we have two brilliant community solutions: Rick Clephas’s KMP-NativeCoroutines (KMP-NC) library and the SKIE Gradle plugin from Touchlab. I’ll focus on the former, as it is the one I have used.

Concurrency by KMP-NC

KMP-NC solves two major limitations: lack of cancellation support for Kotlin suspend functions when converted to async function in Swift and the loss of generics on protocols in Objective-C. Since it generates code through KSP, the export configuration, as discussed previously, will play an important role in ensuring that the generated code uses the correct external types, thereby avoiding errors such as:

Another thing to keep in mind are Exceptions. All Kotlin exceptions are unchecked, meaning that errors are caught at runtime. In contrast, Swift only has checked errors that must be handled at compile time. Therefore, if Swift or Objective-C code calls a Kotlin method that throws an exception, the Kotlin method should be marked with the @Throws annotation, specifying a list of “expected” exception classes.

However, KMP-NC hides the original declaration and removes the @Throws from the generated functions since the generated functions are not designed to throw exceptions. The solution is straightforward: we create a public function that explicitly exposes the types of exceptions that may be thrown, thus adding them to the public API:

Which will be converted to:

Better Exceptions

It is essential for platform teams to iterate over different error types and adjust their UI Layer logic accordingly. In Kotlin, it’s common practice to create a Result<T> sealed class, which represents either success or failure.

When converted to Swift, we get:

The problem with using Nothing as the error type is that it fails when attempting to retrieve the specific errors, such as in a Result<NSArray>:

It occurs because ResultError and ResultSuccess<NSArray> do not share a direct inheritance or subtype relationship. To address this, we adapt Result to use a generic parameter for the error type too:

The compiler will permit the conversion because both ResultError<T> and ResultSuccess<T> become generic instances of Result<T>. This establishes a more flexible relationship between the two types, enabling the cast to work correctly, making the following scenario possible:

This way, the iOS team has access to the specific type of error returned by the Shared Data Layer, rather than simply handling a more generic Swift Error type in a do-catch statement.

Documentation

To provide the best development experience, documentation is also essential. We can leverage Kotlin’s documentation tool, KDoc, to streamline this. To export code documentation for iOS, simply add the following configuration to the iOS targets:

Typical Javadoc’s block tag syntax:

Will be exported to:

Domain

This layer defines the protocols to be implemented by the Data Layer and used by the DI system, helping to minimize the reliance on concrete types from the Shared Data Layer. This approach establishes a clear boundary for communication with the MagicDataLayer, ensuring that it is concentrated within the Data Layer (acting as a bridge) and not spread across other layers of the application, such as the UI Layer.

Inside the Domain package, there is a DomainProtocols library containing a DomainBridge file, where these “bridge protocols” are defined:

These protocols will be used as extensions, allowing concrete types to be referred to by their “domain types.” I’ll demonstrate this shortly.

There is also a CardDomain library, which contains the protocols that will have concrete implementations:

Data

This layer is responsible for implementing the Domain protocols and bridging them with the corresponding Shared Data Layer types. To achieve this, I’ve created a DataBridge file within a DataExtensions library, as shown bellow:

The MagicDataLayer contains types such as KotlinThrowable, RateLimitException, Card, CardSet, and CardsManager. Swift’s ability to extend a class and make it conform to our “domain type” is incredibly useful. From now on, for instance, whenever we need to reference a Card, we’ll use its DomainCard alias type instead (interface).

Lastly, we also have a CardData library, where we will implement the concrete versions of the protocols provided by CardDomain.

The relationship established between the Domain, Data, and Shared Data Layers is crucial for ensuring that dependencies on Shared types are not scattered across all layers. It allows us to leverage a DI system to inject the necessary types where and when needed. For example, the platform team can continue developing the UI Layer using mocks, while the Shared team progresses with their work.

If we think about it, this approach isn’t exclusive to KMP; it also applies to any Swift 3rd-party library we use, or even those we develop ourselves. It also provides a testable architecture.

Presentation

The same philosophy applies to this layer: its classes will have dependencies built based on protocols from the Domain Layer, and the DI system will be responsible for providing the desired instances.

The DomainCardManagerProtocol instance can be either mocked or real, as demonstrated in the following section.

Dependency Injection

So far, we’ve discussed the importance of layering our code to contain dependencies on shared types. Now, let’s delve into how we can efficiently utilize a DI system to provide the required instances.

The Core package contains two libraries: the DI where a DIContainer is defined, and the FactoryProtocols with the following:

The App will be responsible for creating factories for each type needed. For instance, CardsManagerFactory:

This setup allows for easy switching between different types:

Packages and Build Phases

The project’s structure was established using Swift Package Manager (SPM) allowing us to have a package for each layer:

The MagicDataLayer will be integrated by the app’s target Build Phase “Compile Kotlin Framework” script:

But there’s a catch. SPM will try to resolve its dependencies before the Build Phase, which means that packages depending on the MagicDataLayer will fail, since the Build Phase will only run after. This situations arise when no build cache exists or if the Derived Data is cleared. We can solve this situation by replicating this Build Phase script in the app’s scheme Build step by adding a Pre-actions Run Script:

. . .

As always, I hope you find this article useful, thanks for reading. You can explore these strategies in the playground available here:

https://github.com/GuilhE/Magic?source=post_page—–fa8cb2c1aa92——————————–

. . .

This article is previously published on proandroiddev.com