SKILL.md
$28
Choose based on feature complexity, team size, and testing requirements.
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
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.
Decision Framework
- Is the feature a simple CRUD screen? → MV pattern
- Does the screen have complex business logic separate from the view? → MVVM
- Do you need deterministic state transitions and side-effect management? → MVI or TCA
- Is the app large with many independent feature modules? → TCA or Clean Architecture
- 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.
Docs: @Observable)
import Observation
import SwiftUI
@Observable
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.
@Observable
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.
@Observable
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) }
}
@MainActor
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
}
enum Action {
case onAppear
case tripsLoaded([Trip])
case deleteTrip(Trip.ID)
}
@Dependency(\.tripClient) var tripClient
var body: some ReducerOf<Self> {
Reduce { state, action in
switch action {
case .onAppear:
state.isLoading = true
return .run { send in
let trips = try await tripClient.fetchAll()
await send(.tripsLoaded(trips))
}
case .tripsLoaded(let trips):
state.trips = IdentifiedArray(uniqueElements: trips)
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: Large team needs consistent patterns, exhaustive test
coverage is a priority, features compose from smaller features, you need
structured dependency injection across the app.
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
@Observable
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.
@MainActor
protocol Coordinator: AnyObject {
var navigationController: UINavigationController { get }
func start()
}
@MainActor
final class TripCoordinator: Coordinator {
let navigationController: UINavigationController
private let repository: TripRepository
init(navigationController: UINavigationController, repository: TripRepository) {
self.navigationController = navigationController
self.repository = repository
}
func start() {
let vm = TripListViewModel(repository: repository)
vm.onSelectTrip = { [weak self] trip in
self?.showDetail(for: trip)
}
let vc = TripListViewController(viewModel: vm)
navigationController.pushViewController(vc, animated: false)
}
private func showDetail(for trip: Trip) {
let vm = TripDetailViewModel(trip: trip, repository: repository)
vm.onEdit = { [weak self] trip in self?.showEditor(for: trip) }
let vc = TripDetailViewController(viewModel: vm)
navigationController.pushViewController(vc, animated: true)
}
private func showEditor(for trip: Trip) {
// ...
}
}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.
Migration Between Patterns
ObservableObject → @Observable
// Before (iOS 16)
class TripStore: ObservableObject {
@Published var trips: [Trip] = []
}
// View uses @ObservedObject or @StateObject
// After (iOS 17+)
@Observable
class TripStore {
var trips: [Trip] = []
}
// View uses @State for owned, plain property for injectedMVVM → 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
bodycontains 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 instead
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
Mixing architecture patterns inconsistently within a module
One pattern per feature module; different modules can use different patterns
Review Checklist
- Architecture choice is justified by feature complexity and team needs
@Observableused instead ofObservableObjectfor iOS 17+ targets
- Dependencies are injected, not created internally (testability)
- Navigation logic is separated from business logic
- 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
References
- Apple docs: Observation | Observable)