TCA, Dependencies and Clean Architecture in single app

[jankase]

Introduction

We are starting a complete revamp of the legacy iOS application. The application is quite complex (100k+ lines of source code). Because of the significant complexity, we want to use Clean Architecture layering with TCA as the primary technology for the presentation layer in conjunction with SwiftUI. We are looking for a pragmatic way to use these technologies side by side and not over-engineer the whole solution. We want to leverage other libraries from the TCA ecosystem (such as Dependencies) on different layers. Here, I'm providing only the blueprint we are preparing for the development team.

Any feedback or ideas for improvement would be appreciated.

Structure

Modules should split the application, and each module should be divided into layers into independent packages that allow access restriction.

I will not explain all the principles of clean architecture. Many good articles are available on the web.

We are considering creating a single package with several products for each module. The structure should be the following:

• PackageA
  • PackageAData
  • PackageADomain
  • PackageAPresentation

The domain layer does not depend on other layers. Code has visibility only for classes/structs and protocols defined inside this package. Besides protocols for UCs, which implement business logic, there are protocols for Repositories. These protocols allow for the invocation of data layer functionalities, but the actual implementation of these protocols is not part of this layer.

The data layer depends only on the domain layer. It should be responsible for communicating with the backend or local storage. It implements Repositories defined on the domain layer to provide the output of these operations to the domain layer. Typically, the data models on the data layer and domain layer do not match, so it is necessary to convert the output into the domain model to provide an understandable structure to the domain layer.

The presentation layer should depend only on the domain layer. The presentation could not access the data layer, and it must be impossible to invoke any functionalities directly from the data layer. It must not be possible to import PackageAData in PackageAPresentation.

This is a strict, Clean Architecture approach.

Problem

On the domain layer, we defined simple UC, which will use a repository to retrieve the data. The repository implementation is not visible to the domain layer, so it is impossible to immediately provide the liveValue for the repository key on the domain layer. A small sample follows:

import Dependencies
import Foundation

public protocol FetchFinancialDataUC: Sendable {
    func execute() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
}

public protocol FinancialRepository: Sendable {
    func fetchFinancialData() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
}

struct FetchFinancialDataUCImpl: FetchFinancialDataUC {
    @Dependency(\.financialRepository) var financialRepository
    
    func execute() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig]) {
        return try await financialRepository.fetchFinancialData()
    }
}

struct FetchFinancialDataUCKey: DependencyKey {
    static let liveValue: FetchFinancialDataUC = FetchFinancialDataUCImpl()
}

public extension DependencyValues {
    var fetchFinancialDataUC: FetchFinancialDataUC {
        get { self[FetchFinancialDataUCKey.self] }
        set { self[FetchFinancialDataUCKey.self] = newValue }
    }
}

struct FinancialRepositoryKey: DependencyKey {
    static let liveValue: FinancialRepository = {
        fatalError()
    }()
}

public extension DependencyValues {
    var financialRepository: FinancialRepository {
        get { self[FinancialRepositoryKey.self] }
        set { self[FinancialRepositoryKey.self] = newValue }
    }
}

On the data layer, the implementation of the FinancialRepository is provided.

import FinancialKPIDomain
import Dependencies
import Foundation

struct FinancialRepositoryImpl: FinancialRepository {
    
    @Dependency(\.dataProviderService) var dataProviderService
    
    func fetchFinancialData() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig]) {
        let data = try await dataProviderService.fetchData()
        
        struct ServerResponse: Decodable {
            let data: [FinancialData]
            let columns: [ColumnConfig]
            let filters: [FilterConfig]
        }
        
        let response = try JSONDecoder().decode(ServerResponse.self, from: data)
        return (response.data, response.columns, response.filters)
    }
    
}

Because the implementation is not public, it needs to be there also some method which can push it to the dependency container:

import FinancialKPIDomain
import Foundation
import Dependencies

public func injectDependenciesFinancialKPI(dependencies: inout DependencyValues) {
    dependencies.financialRepository = FinancialRepositoryImpl()
}

On the application layer, then, we can easily set up the dependency container during app initialisation:

import FinancialKPIData
import FinancialKPIPresentation
import ComposableArchitecture
import Dependencies
import SwiftUI

@main
struct TCASampleApp: App {
    init() {
        prepareDependencies { dep in
            injectDependenciesFinancialKPI(dependencies: &dep)
        }
    }
    
    var body: some Scene {
        WindowGroup {
            FinancialDataView(store: Store(initialState: FinancialDataFeature.State(), reducer: {
                FinancialDataFeature()
            }))
        }
    }
}

The presentation layer can then use the use case without problem when it runs in the simulator or on a physical device. Here is the shortened presentation layer.

import Common
import Dependencies
import FinancialKPIDomain
import Foundation

struct FinancialDataClient: DependencyKey, Sendable {
    var fetchData: @Sendable () async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
    
    static let liveValue: FinancialDataClient = {
        FinancialDataClient {
            @Dependency(\.fetchFinancialDataUC) var fetchFinancialDataUC
            return try await fetchFinancialDataUC.execute()
        }
    }()    
}

extension DependencyValues {
    var financialDataClient: FinancialDataClient {
	    ...
    }
}

import FinancialKPIDomain
import ComposableArchitecture
import Dependencies
import Foundation

@Reducer
public struct FinancialDataFeature {
    @ObservableState
    public struct State: Equatable {
	    ...
    }

    @CasePathable
    public enum Action: BindableAction {
      ...
    }
    
    @Dependency(\.financialDataClient.fetchData) var fetchData
    
    public init() {}

    public var body: some ReducerOf<Self> {
        BindingReducer()
        Reduce { state, action in
            switch action {
            ...
            case .fetchData:
                state.isLoading = true
                state.errorMessage = nil
                return .run { [fetchData = self.fetchData] send in
                    let result = try await fetchData()
                    await send(.dataLoaded(.success(result)))
                } catch: { error, send in
                    await send(.dataLoaded(.failure(error)))
                }
            case .dataLoaded(let result):
                state.isLoading = false
                switch result {
                case let .success((data, columns, filters)):
                    state.data = data
                    state.columns = columns
                    state.filters = filters
                    for filter in filters {
                        state.selectedFilters[filter.key] = filter.options.first
                    }
                case let .failure(error):
                    state.errorMessage = error.localizedDescription
                }
                return .none
            ...
            }
        }
    }
}

As I wrote, this solution works fine for runtime but starts failing during preview.

import ComposableArchitecture
import SwiftUI


public struct FinancialDataView: View {
    @Bindable var store: StoreOf<FinancialDataFeature>
    
    public init(store: StoreOf<FinancialDataFeature>) {
        self.store = store
    }
    
    public var body: some View {
        VStack {
        ...
        }
        .navigationTitle("Financial Data")
        .onAppear {
            store.send(.fetchData)
        }
    }
}

#Preview {
    FinancialDataView(store: Store(initialState: FinancialDataFeature.State(), reducer: {
        FinancialDataFeature()
    }))
}

Currently, the FinancialRepositoryKey.liveValue ends with fatalError, and the preview fails.

As I mentioned, the data layer should not be visible from the presentation layer, so the problem cannot be resolved using the withDependencies function.

Potential solutions

Mock data on feature client

One solution is to mock data on the feature’s client.

struct FinancialDataClient: DependencyKey, Sendable {
    var fetchData: @Sendable () async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
    
    ...
    
    static let previewValue: FinancialDataClient = {
        let data = """
        {
          "data": [
            {
              "id": "c56a4180-65aa-42ec-a945-5fd21dec0538",
              "values": {
                "symbol": "AAPL",
                "price": "178.40",
                "change": "+0.50%"
              }
            },
            {
              "id": "e07b8e3f-2f4a-4d9d-8e9d-7d29a4d527c3",
              "values": {
                "symbol": "GOOG",
                "price": "132.20",
                "change": "-0.20%"
              }
            }
          ],
          "columns": [
            { "key": "symbol", "title": "Symbol" },
            { "key": "price", "title": "Price" },
            { "key": "change", "title": "Daily Change" }
          ],
          "filters": [
            { "key": "market", "options": ["NASDAQ", "NYSE"] },
            { "key": "sector", "options": ["Technology", "Finance", "Healthcare"] }
          ]
        }
        """.data(using: .utf8)!
        struct Wrapper: Decodable, Sendable {
            let data: [FinancialData]
            let columns: [ColumnConfig]
            let filters: [FilterConfig]
        }
        let result = try! JSONDecoder().decode(Wrapper.self, from: data)
        return FinancialDataClient {
            return (result.data, result.columns, result.filters)
        }
    }()
}

I don’t like this solution because it moves some “data-related” functionality to the presentation layer and duplicates some data logic. Here, it is simple, but the logic will be more complex in the actual application, and maintaining consistency will not be easy.

Introduce the DI package

One team member has proposed one alternative. Introducing new layer DI. The package structure would be something like this:

• PackageA
  • PackageAData
  • PackageADI
  • PackageADomain
  • PackageAPresentation
    The dependencies will be the same as in the previous model, with only one exception: The presentation layer will now depend on the DI layer, too.

The DI layer depends on domain and data layers.

The implementation of UC would not use Dependencies at all. For injection, it is used standard initialisation injection:

import Dependencies
import Foundation

struct FetchFinancialDataUCImpl: FetchFinancialDataUC {
    var financialRepository: FinancialRepository
    
    func execute() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig]) {
        return try await financialRepository.fetchFinancialData()
    }
}

public func fetchFinancialDataUCFactory(financialRepository: any FinancialRepository) -> FetchFinancialDataUC {
    FetchFinancialDataUCImpl(financialRepository: financialRepository)
}

The implementation itself is hidden behind the factory function.

The DependencyKey implementation for the repository is moved into the data layer.

The DependencyKey for UC is moved to the DI layer, where it is correctly initialised with the usage repository from the data layer.

import Dependencies
import FinancialKPIData
import FinancialKPIDomain

struct FetchFinancialDataUCKey: DependencyKey {
    static let liveValue: FetchFinancialDataUC = {
        @Dependency(\.financialRepository) var financialDataRepository
        return fetchFinancialDataUCFactory(financialRepository: financialDataRepository)
    }()
}

public extension DependencyValues {
    
    var fetchFinancialDataUC: FetchFinancialDataUC {
        get {
            self[FetchFinancialDataUCKey.self]
        }
        set {
            self[FetchFinancialDataUCKey.self] = newValue
        }
    }
}

The featured client then depends on the UC. There is no need to mock data for preview. It is handled on the data layer.

import Common
import Dependencies
import FinancialKPIDI
import FinancialKPIDomain
import Foundation

struct FinancialDataClient: DependencyKey, Sendable {
    var fetchData: @Sendable () async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
    
    static let liveValue: FinancialDataClient = {
        FinancialDataClient {
            @Dependency(\.fetchFinancialDataUC) var fetchFinancialDataUC
            return try await fetchFinancialDataUC.execute()
        }
    }()
}

extension DependencyValues {
    var financialDataClient: FinancialDataClient {
	    ...
    }
}

The issue with this solution is that the presentation layer can access repositories from the data layer in this configuration. This means that in this solution, we are losing the main advantage of using separate packages—restricting the use of the data layer from the presentation layer on the compilation level.

Here is an example:

import Common
import Dependencies
import FinancialKPIDI
import FinancialKPIData
import FinancialKPIDomain
import Foundation

struct FinancialDataClient: DependencyKey, Sendable {
    var fetchData: @Sendable () async throws -> ([FinancialData], [ColumnConfig], [FilterConfig])
    
    static let liveValue: FinancialDataClient = {
        FinancialDataClient {
            @Dependency(\.financialRepository) var repository
            return try await repository.fetchFinancialData()
        }
    }()
}

extension DependencyValues {
    var financialDataClient: FinancialDataClient {
	    ...
    }
}

Pragmatic solution

Remove UCs from the domain layer and keep only the domain model shared among the presentation and data layers. This does not strictly follow clean architecture principles, but based on experience, most UCs look the same as in the example above. It is adding a boilerplate with almost no added value. Dependency clients can directly access repositories, as mentioned in the last example. I’m not sure if there are drawbacks to this simplification.

[lukeredpath]

Maybe I’m missing something here but why doesn’t your domain layer just conform to TestDependencyKey and provide reasonable test and preview values then your data layer which provides the live implementation conform to DependencyKey?

[jankase]

Thank you for your answer. I’m not sure how this separation would help me.

I tried to implement your suggestion, but I’m probably doing it incorrectly. I’m attaching my changes.

I’ve made the key public in the domain model and followed only TestDependencyKey. Because I don’t have access to the data layer, I must provide only a fatalError response like this:

public struct FinancialRepositoryKey: TestDependencyKey {
    public static var testValue: any FinancialRepository {
        fatalError("Implementation not available")
    }
    
    public static var previewValue: any FinancialRepository {
        fatalError("Implementation not available")
    }
}

Unfortunately, this is not solving my issue with the preview and duplication of code.

I tried to extend the data layer the key to conform to the DependencyKey protocol this way:

public extension FinancialRepositoryKey: DependencyKey {
    public static var liveValue: any FinancialRepository {
        FinancialRepositoryImpl()
    }
}

But this is impossible also because of the following compilation error.

'public' modifier cannot be used with extensions that declare protocol conformances.

But I’m probably doing something incorrectly.

[lukeredpath]

You don't need to use fatalError(). You should return a test implementation instead. If you use the protocol-witness style of dependency you get this for free but as you're using a protocol you need to provide your own test implementation.

You simply don't need to add public to your DependencyKey extension as the error suggests. As long as that module is visible to your app at the point it all integrates together the live dependency will get used.

[jankase]

As I wrote before, there are dependency issues. Each layer has its package, and there are defined dependencies between them. Classes in the data layer (even the public) are not visible in the domain layer. The dependency is in the opposite direction. The data layer depends on the domain layer.

You propose a solution described under Mock data on feature client shifted to the domain layer. So, I have the same objection in this case, too:

I don’t like this solution because it moves some “data-related” functionality to the presentation layer and duplicates some data logic. Here, it is simple, but the logic will be more complex in the actual application, and maintaining consistency will not be easy.

In this case, we are just moving data logic to the domain layer, but the principle is the same.

Because packages separate layers, a key must be defined as public. Otherwise, extending it in the data layer would not be possible.

Even if the extension of the public key were possible, I’m afraid that presentation logic would have to depend on the data layer to see the liveValue implemented on the data layer, but this is only speculative.

[lukeredpath]

I'm struggling to see what the issue is here.

Your domain layer defines a FinancialRepository protocol - this is a domain concept. It is perfectly reasonable for the domain layer to create a TestDependencyKey conformance and provide, at minimum, a test value that defines some kind of basic implementation. It could be as simple as:

struct UnimplementedRepository: FinancialRepository {
  func fetchFinancialData() async throws -> ([FinancialData], [ColumnConfig], [FilterConfig]) {
    reportIssue("Unimplemented")
    return ([], [], []) // for example
  }
}

This is enough to register the repository type as a dependency. There is no dependency issues here. You aren't moving any logic to the domain layer - there isn't any logic, it's just a test stub. You will likely override this in your tests of any component that depends on this type.

The data layer provides the real, live implementation of this protocol. It should be the one that conforms to the DependencyKey protocol and provides the live value. This extension does not need to be made public.

There has to be a point at which all of your different layers come together, for example the app target. This can link to your data layer which will in turn link to your domain layer and your live implementation will get picked up at runtime without either the domain layer or presentation layer needing to know anything about it.

[lukeredpath]

Alternatively, instead of defining the DependencyKey and live values in the data layer itself, you could move all of these conformances to an integration module (or the app target itself). I've used both approaches in our app.

For example, we have an AnalyticsClient dependency in our app that provides a test value (just a no-op implementation) and conforms to TestDependencyKey and extends DependencyValues. We have a separate MixpanelAnalyticsClient that provides the live implementation and has a dependency on the third-party Mixpanel SDK. None of our other modules need to depend on this as they only depend on the interface in the AnalyticsClient package. The MixpanelAnalyticsClient module itself doesn't define a live dependency value.

In our root App module, we link to the MixpanelAnalyticsClient module and conform AnalyticsClient to DependencyKey and return a MixpanelAnalyticsClient() as the live value. It all works as you'd expect.

[AgapovOne]

we want to use Clean Architecture

We are looking for a pragmatic way to use these technologies side by side and not over-engineer the whole solution.

I don't see how Clean architecture is not that over-engineering that you want to avoid.

Layers over layers to get... What? To force every developer to travel through lots of files to see what even the simplest things do?

Can you elaborate why you need Clean?