Skill v1.0.2
currentAutomated scan100/100~2 modified
version: "1.0.2" 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
- 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.
import Observationimport SwiftUI@MainActor@Observablefinal class TripStore {var trips: [Trip] = []var isLoading = falsevar error: Error?private let service: TripServiceinit(service: TripService) {self.service = service}func loadTrips() async {isLoading = truedefer { 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 inTripRow(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@Observablefinal class TripListViewModel {private(set) var trips: [TripRowItem] = []private(set) var isLoading = falsevar searchText = ""var filteredTrips: [TripRowItem] {guard !searchText.isEmpty else { return trips }return trips.filter { $0.name.localizedStandardContains(searchText) }}private let repository: TripRepositoryinit(repository: TripRepository) {self.repository = repository}func loadTrips() async {isLoading = truedefer { 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: UUIDlet name: Stringlet dateRange: Stringinit(from trip: Trip) {self.id = trip.idself.name = trip.nameself.dateRange = trip.startDate.formatted(.dateTime.month().day())+ " – " + trip.endDate.formatted(.dateTime.month().day())}}struct TripListView: View {@State private var viewModel: TripListViewModelinit(repository: TripRepository) {_viewModel = State(initialValue: TripListViewModel(repository: repository))}var body: some View {List {ForEach(viewModel.filteredTrips) { item inText(item.name)}.onDelete { offsets inTask { 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@Observablefinal class TripListStore {private(set) var state = State()struct State {var trips: [Trip] = []var isLoading = falsevar error: String?}enum Intent {case loadTripscase deleteTrip(Trip)case clearError}private let service: TripServiceinit(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 = truedo {state.trips = try await service.fetchTrips()} catch {state.error = error.localizedDescription}state.isLoading = falsecase .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@Reducerstruct TripList {@ObservableStatestruct State: Equatable {var trips: IdentifiedArrayOf<Trip> = []var isLoading = falsevar errorMessage: String?}enum Action {case onAppearcase tripsLoaded([Trip])case tripsFailed(String)case deleteTrip(Trip.ID)}@Dependency(\.tripClient) var tripClientvar body: some ReducerOf<Self> {Reduce { state, action inswitch action {case .onAppear:state.isLoading = truestate.errorMessage = nilreturn .run { send indo {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 = falsereturn .nonecase .tripsFailed(let message):state.errorMessage = messagestate.isLoading = falsereturn .nonecase .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 layerprotocol TripRepository: Sendable {func fetchAll() async throws -> [Trip]func save(_ trip: Trip) async throwsfunc delete(id: UUID) async throws}struct FetchUpcomingTripsUseCase: Sendable {private let repository: TripRepositoryinit(repository: TripRepository) {self.repository = repository}func execute() async throws -> [Trip] {try await repository.fetchAll().filter { $0.startDate > .now }.sorted { $0.startDate < $1.startDate }}}// Data layerstruct RemoteTripRepository: TripRepository {private let client: APIClientfunc fetchAll() async throws -> [Trip] {try await client.request(.get, "/trips")}// ...}// Presentation layer@MainActor@Observablefinal class UpcomingTripsViewModel {private(set) var trips: [Trip] = []private let useCase: FetchUpcomingTripsUseCaseinit(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@Observablefinal 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
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; 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@Bindablewiring hand off toswiftui-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