---

name: architecture-patterns description: Choose and implement iOS architecture patterns (MVVM, TCA, Clean Architecture) based on feature complexity. Use when designing architecture for new features or refactoring existing code.

Architecture Patterns

Overview

Quick reference for choosing and implementing iOS architecture patterns. Focused on decision criteria, not tutorials.

Pattern Selection

Decision Tree

Copy1. Single screen + local state only?
   → MV (SwiftUI View + @State)

2. Business logic or shared state?
   → MVVM

3. Complex state transitions?
   → TCA

4. Multi-team, high modularity?
   → Clean Architecture

MVVM Pattern (Most Common)

Structure:

• ViewModels: @Observable, protocol-based DI
• Views: @State private var viewModel
• Services: Protocols for testability

Critical Rules:

• ✅ Protocol-based DI via init (enables mocking)
• ✅ @MainActor for state updates
• ✅ Keep Views dumb (delegate to ViewModel)
• ❌ Never import SwiftUI in ViewModels
• ❌ Never use @Published (use @Observable)
• ❌ Never make ViewModels optional

Minimal Example:

Copyprotocol AuthServiceProtocol {
    func login(_ email: String, _ password: String) async throws -> User
}

@Observable
final class LoginViewModel {
    private let authService: AuthServiceProtocol
    var email = ""
    var password = ""
    var isLoading = false

    init(authService: AuthServiceProtocol = AuthService()) {
        self.authService = authService
    }

    @MainActor
    func login() async {
        isLoading = true
        defer { isLoading = false }
        try? await authService.login(email, password)
    }
}

struct LoginView: View {
    @State private var viewModel = LoginViewModel()
    var body: some View {
        Form {
            TextField("Email", text: $viewModel.email)
            SecureField("Password", text: $viewModel.password)
            Button("Login") { Task { await viewModel.login() } }
                .disabled(viewModel.isLoading)
        }
    }
}

TCA Pattern

Use for: Complex state machines, side effects, time-travel debugging

Key: Single Reducer with State/Action/Dependencies. Exhaustive testing via TestStore.

Reference: TCA documentation

Clean Architecture

Use for: Enterprise apps, multiple teams, maximum testability

Patterns:

• VIP (View-Interactor-Presenter): Use vip-clean-architecture skill for unidirectional data flow, protocol-based boundaries, and Spy-pattern testing
• Generic Clean: Domain (entities, use cases) → Data (repositories, network) → Presentation (ViewModels, Views)

Key: Dependency inversion, protocol-based boundaries between layers

References

For detailed implementation examples and migration guides, see:

• references/mvvm-patterns.md
• references/tca-guide.md
• references/clean-architecture.md

---

Word count: ~300 (was 2,863) For: Senior/mid iOS engineers who know how to code Focus: Decision-making, not hand-holding