swift-architecture

---

name: swift-architecture description: "Select, implement, or migrate between app architecture patterns for Apple platform apps. Use when choosing between MV (Model-View with @Observable), MVVM, MVI, TCA (The Composable Architecture), Clean Architecture, VIPER, or Coordinator patterns; when evaluating architecture fit for a feature's complexity; when migrating from one pattern to another; or when reviewing whether an app's current architecture is appropriate. Scoped to Apple-platform patterns using Swift 6.3, SwiftUI, and UIKit."

Swift Architecture

Select and implement the right architecture pattern for Apple platform apps built with Swift 6.3 and SwiftUI or UIKit.

Contents

• Scope Boundary
• Architecture Selection
• MV Pattern (Model-View with @Observable)
• MVVM
• MVI (Model-View-Intent)
• TCA (The Composable Architecture)
• Clean Architecture
• Coordinator Pattern
• VIPER
• Migration Between Patterns
• Common Mistakes
• Review Checklist
• References

Scope Boundary

This skill owns architecture-level decisions: pattern selection, module boundaries, dependency direction, migration/escalation strategy, and structural test strategy. It does not own SwiftUI state mechanics; route @State, @Bindable, @Environment, edit-sheet/local state, bindings, view composition, and @Observable MV implementation mechanics to swiftui-patterns. Use swiftui-navigation for NavigationStack, NavigationSplitView, NavigationPath, route models, sheets, tabs, and deep-link URL handling; swift-concurrency for @MainActor, default MainActor isolation, Sendable, strict-concurrency diagnostics, and data-race diagnostics; and swift-testing for @Test, #expect, #require, fixtures, parameterized tests, mocks, stubs, and suite organization.

Architecture Selection

Pattern	Best For	Complexity	Testability
MV	Small-to-medium SwiftUI apps, rapid iteration	Low	Moderate
MVVM	Medium apps, teams familiar with reactive patterns	Medium	High
MVI	Complex state machines, predictable state flow	Medium-High	High
TCA	Large apps needing composable features, strong testing	High	Very High
Clean Architecture	Enterprise apps, strict separation of concerns	High	Very High
Coordinator	Apps with complex navigation flows (UIKit or hybrid)	Medium	High
VIPER	Legacy UIKit modules already using VIPER boundaries	Very High	High

Default recommendation for new SwiftUI apps: Start with MV (Model-View with @Observable). Escalate to MVVM or TCA only when the feature's complexity demands it.

Boundary-split answers should use one swift-architecture bucket for pattern/module/dependency/migration/test-strategy decisions. Do not add a separate architecture-owned "SwiftUI state ownership" bucket; property-wrapper, local binding, navigation, concurrency-diagnostic, fixture, and parameterized test mechanics are sibling-skill handoffs.

Decision Framework

1. Is the feature a simple CRUD screen? → MV pattern
2. Does the screen have complex business logic separate from the view? → MVVM
3. Do you need deterministic state transitions and side-effect management? → MVI or TCA
4. Is the app large with many independent feature modules? → TCA or Clean Architecture
5. Is navigation complex with deep linking and conditional flows? → Add Coordinator pattern

MV Pattern

The simplest SwiftUI architecture. The view observes @Observable models directly. No intermediate view model layer.

import Observation
import SwiftUI

@MainActor
@Observable
final class TripStore {
    var trips: [Trip] = []
    var isLoading = false
    var error: Error?

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        do {
            trips = try await service.fetchTrips()
        } catch {
            self.error = error
        }
    }

    func deleteTrip(_ trip: Trip) async throws {
        try await service.delete(trip)
        trips.removeAll { $0.id == trip.id }
    }
}

struct TripsView: View {
    @State private var store = TripStore(service: .live)

    var body: some View {
        List(store.trips) { trip in
            TripRow(trip: trip)
        }
        .task { await store.loadTrips() }
    }
}

When MV is enough: Single-screen features, prototype/MVP, small teams, straightforward data flow.

When to upgrade: Business logic grows complex, unit testing the view's behavior becomes difficult, multiple views need to share and transform the same state differently.

MVVM

Separates view logic into a ViewModel that the view observes. The view model transforms model data for display and handles user actions.

@MainActor
@Observable
final class TripListViewModel {
    private(set) var trips: [TripRowItem] = []
    private(set) var isLoading = false
    var searchText = ""

    var filteredTrips: [TripRowItem] {
        guard !searchText.isEmpty else { return trips }
        return trips.filter { $0.name.localizedStandardContains(searchText) }
    }

    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func loadTrips() async {
        isLoading = true
        defer { isLoading = false }
        let models = (try? await repository.fetchAll()) ?? []
        trips = models.map { TripRowItem(from: $0) }
    }

    func delete(at offsets: IndexSet) async {
        let toDelete = offsets.map { filteredTrips[$0] }
        for item in toDelete {
            try? await repository.delete(id: item.id)
        }
        await loadTrips()
    }
}

struct TripRowItem: Identifiable {
    let id: UUID
    let name: String
    let dateRange: String

    init(from trip: Trip) {
        self.id = trip.id
        self.name = trip.name
        self.dateRange = trip.startDate.formatted(.dateTime.month().day())
            + " – " + trip.endDate.formatted(.dateTime.month().day())
    }
}

struct TripListView: View {
    @State private var viewModel: TripListViewModel

    init(repository: TripRepository) {
        _viewModel = State(initialValue: TripListViewModel(repository: repository))
    }

    var body: some View {
        List {
            ForEach(viewModel.filteredTrips) { item in
                Text(item.name)
            }
            .onDelete { offsets in
                Task { await viewModel.delete(at: offsets) }
            }
        }
        .searchable(text: $viewModel.searchText)
        .task { await viewModel.loadTrips() }
    }
}

Testing a ViewModel:

@Test func filteredTripsMatchesSearch() async {
    let repo = MockTripRepository(trips: [
        Trip(name: "Paris"), Trip(name: "Tokyo"), Trip(name: "Paris TX")
    ])
    let vm = TripListViewModel(repository: repo)
    await vm.loadTrips()
    vm.searchText = "Paris"
    #expect(vm.filteredTrips.count == 2)
}

MVI

Unidirectional data flow: views dispatch intents, a reducer produces new state, and side effects are handled explicitly.

@MainActor
@Observable
final class TripListStore {
    private(set) var state = State()

    struct State {
        var trips: [Trip] = []
        var isLoading = false
        var error: String?
    }

    enum Intent {
        case loadTrips
        case deleteTrip(Trip)
        case clearError
    }

    private let service: TripService

    init(service: TripService) {
        self.service = service
    }

    func send(_ intent: Intent) {
        Task { await handle(intent) }
    }

    private func handle(_ intent: Intent) async {
        switch intent {
        case .loadTrips:
            state.isLoading = true
            do {
                state.trips = try await service.fetchTrips()
            } catch {
                state.error = error.localizedDescription
            }
            state.isLoading = false

        case .deleteTrip(let trip):
            try? await service.delete(trip)
            state.trips.removeAll { $0.id == trip.id }

        case .clearError:
            state.error = nil
        }
    }
}

Advantages: Predictable state transitions, easy to log/replay intents, clear separation of "what happened" from "what changed."

TCA

The Composable Architecture (Point-Free) provides composable reducers, dependency injection, exhaustive testing, and structured side effects.

Docs: TCA

import ComposableArchitecture

@Reducer
struct TripList {
    @ObservableState
    struct State: Equatable {
        var trips: IdentifiedArrayOf<Trip> = []
        var isLoading = false
        var errorMessage: String?
    }

    enum Action {
        case onAppear
        case tripsLoaded([Trip])
        case tripsFailed(String)
        case deleteTrip(Trip.ID)
    }

    @Dependency(\.tripClient) var tripClient

    var body: some ReducerOf<Self> {
        Reduce { state, action in
            switch action {
            case .onAppear:
                state.isLoading = true
                state.errorMessage = nil
                return .run { send in
                    do {
                        let trips = try await tripClient.fetchAll()
                        await send(.tripsLoaded(trips))
                    } catch {
                        await send(.tripsFailed(error.localizedDescription))
                    }
                }
            case .tripsLoaded(let trips):
                state.trips = IdentifiedArray(uniqueElements: trips)
                state.isLoading = false
                return .none
            case .tripsFailed(let message):
                state.errorMessage = message
                state.isLoading = false
                return .none
            case .deleteTrip(let id):
                state.trips.remove(id: id)
                return .run { _ in try await tripClient.delete(id) }
            }
        }
    }
}

Use TCA when: You need deterministic state transitions for complex state flows, structured side-effect sequencing, feature composition, strong reducer testing, or app-wide dependency injection.

Clean Architecture

Layers: Domain (entities, use cases, repository protocols) → Data (repository implementations, network, persistence) → Presentation (views, view models). Dependencies point inward.

// Domain layer
protocol TripRepository: Sendable {
    func fetchAll() async throws -> [Trip]
    func save(_ trip: Trip) async throws
    func delete(id: UUID) async throws
}

struct FetchUpcomingTripsUseCase: Sendable {
    private let repository: TripRepository

    init(repository: TripRepository) {
        self.repository = repository
    }

    func execute() async throws -> [Trip] {
        try await repository.fetchAll()
            .filter { $0.startDate > .now }
            .sorted { $0.startDate < $1.startDate }
    }
}

// Data layer
struct RemoteTripRepository: TripRepository {
    private let client: APIClient

    func fetchAll() async throws -> [Trip] {
        try await client.request(.get, "/trips")
    }
    // ...
}

// Presentation layer
@MainActor
@Observable
final class UpcomingTripsViewModel {
    private(set) var trips: [Trip] = []
    private let useCase: FetchUpcomingTripsUseCase

    init(useCase: FetchUpcomingTripsUseCase) {
        self.useCase = useCase
    }

    func load() async {
        trips = (try? await useCase.execute()) ?? []
    }
}

Use Clean Architecture when: Strict separation is required (enterprise, regulated domains), the domain layer must be testable without any framework dependencies, or multiple presentation targets share the same business logic.

Coordinator Pattern

Separates navigation logic from views. Especially useful in UIKit or hybrid apps with complex navigation flows.

Keep Coordinators @MainActor, inject dependencies at coordinator creation, and pass user-selection callbacks from view models or controllers back to the coordinator. The coordinator owns push/modal decisions; feature models own business logic.

In pure SwiftUI apps, NavigationStack with path-based routing often replaces the Coordinator pattern. Use Coordinators when you need UIKit integration or shared navigation logic across platforms.

VIPER

VIPER splits a feature into View, Interactor, Presenter, Entity, and Router roles. Treat it as a maintenance pattern for apps that already have strict UIKit module boundaries rather than a default for new SwiftUI work.

Use VIPER when: An existing UIKit codebase already organizes screens as VIPER modules, teams need explicit handoff contracts between presentation, business logic, and routing, or a migration must preserve module boundaries while modernizing internals.

Avoid VIPER when: A new SwiftUI feature can use MV, MVVM, TCA, or Clean Architecture with fewer files and clearer data flow.

Migration Between Patterns

ObservableObject → @Observable

// Before (iOS 16)
class TripStore: ObservableObject {
    @Published var trips: [Trip] = []
}
// View uses @ObservedObject or @StateObject

// After (iOS 17+)
@MainActor
@Observable
final class TripStore {
    var trips: [Trip] = []
}
// View uses @State for owned; plain injection or @Bindable only when needed

Migration routing: keep Coordinators for UIKit or hybrid boundaries; pure SwiftUI flows usually own NavigationStack/path state. Route detailed route enums, NavigationSplitView, sheets, tabs, and deep links to swiftui-navigation, strict-concurrency diagnostics to swift-concurrency, and fixtures or parameterized tests to swift-testing. Migrate per feature module, not app-wide by default; keep each module internally consistent while allowing different modules to use different patterns during incremental adoption.

MVVM → MV (simplifying)

If a view model only passes through model data without transforming it, remove the view model and let the view observe the model directly.

MV → MVVM (scaling up)

Extract business logic and data transformation into a view model when:

• The view's body contains conditional logic for data formatting
• Multiple views need different projections of the same model
• You need to test logic without instantiating views

Any → TCA

TCA adoption is typically incremental: wrap one feature's state and actions in a Reducer, migrate its dependencies to @Dependency, and test.

Common Mistakes

Mistake	Fix
Using ObservableObject in new iOS 17+ code	Use @Observable; isolate UI-observed app state to @MainActor for Swift 6 data-race safety
View model that only forwards model properties	Remove the view model; use MV pattern
Massive view model with navigation, networking, and formatting	Split into focused collaborators (coordinator, service, formatter)
Choosing TCA for a two-screen app	Start with MV; adopt TCA when composition and testing demands justify it
Protocol-heavy Clean Architecture for a simple feature	Match architecture complexity to feature complexity
Coordinator pattern in pure SwiftUI without UIKit needs	Use NavigationStack path-based routing instead
Starting new SwiftUI modules with VIPER	Reserve VIPER for legacy UIKit maintenance or strict module-boundary migrations
Mixing architecture patterns inside one feature module	Keep one pattern inside each feature module; migrate different modules independently when needed

Review Checklist

• Architecture choice is justified by feature complexity and team needs
• Architecture identifies the model/store owner; @State, plain injection, and @Bindable wiring hand off to swiftui-patterns
• Dependencies are injected, not created internally (testability)
• SwiftUI MV mechanics, NavigationSplitView, strict-concurrency diagnostics, fixtures, and parameterized tests hand off to sibling skills explicitly
• State mutations happen in a clear, auditable location
• View models (if present) are testable without views
• No god objects — responsibilities are distributed appropriately
• Pattern is consistent within each feature module, including during migrations

References

• Apple docs: Observation | Observable
• Apple docs: Migrating from ObservableObject to Observable
• Apple docs: State | Bindable | Environment
• Apple docs: NavigationStack
• Apple docs: Swift Testing
• TCA docs: ComposableArchitecture