axiom-swiftui-architecture

SwiftUI Architecture

When to Use This Skill

Use this skill when:

• You have logic in your SwiftUI view files and want to extract it
• Choosing between MVVM, TCA, vanilla SwiftUI patterns, or Coordinator
• Refactoring views to separate concerns
• Making SwiftUI code testable
• Asking "where should this code go?"
• Deciding which property wrapper to use (@State, @Environment, @Bindable)
• Organizing a SwiftUI codebase for team development

Example Prompts

What You Might Ask	Why This Skill Helps
"There's quite a bit of code in my model view files about logic things. How do I extract it?"	Provides refactoring workflow with decision trees for where logic belongs
"Should I use MVVM, TCA, or Apple's vanilla patterns?"	Decision criteria based on app complexity, team size, testability needs
"How do I make my SwiftUI code testable?"	Shows separation patterns that enable testing without SwiftUI imports
"Where should formatters and calculations go?"	Anti-patterns section prevents logic in view bodies
"Which property wrapper do I use?"	Decision tree for @State, @Environment, @Bindable, or plain properties

Quick Architecture Decision Tree

What's driving your architecture choice?
│
├─ Starting fresh, small/medium app, want Apple's patterns?
│  └─ Use Apple's Native Patterns (Part 1)
│     - @Observable models for business logic
│     - State-as-Bridge for async boundaries
│     - Property wrapper decision tree
│
├─ Familiar with MVVM from UIKit?
│  └─ Use MVVM Pattern (Part 2)
│     - ViewModels as presentation adapters
│     - Clear View/ViewModel/Model separation
│     - Works well with @Observable
│
├─ Complex app, need rigorous testability, team consistency?
│  └─ Consider TCA (Part 3)
│     - State/Action/Reducer/Store architecture
│     - Excellent testing story
│     - Learning curve + boilerplate trade-off
│
└─ Complex navigation, deep linking, multiple entry points?
   └─ Add Coordinator Pattern (Part 4)
      - Can combine with any of the above
      - Extracts navigation logic from views
      - NavigationPath + Coordinator objects

---

Part 1: Apple's Native Patterns (iOS 26+)

Core Principle

"A data model provides separation between the data and the views that interact with the data. This separation promotes modularity, improves testability, and helps make it easier to reason about how the app works." — Apple Developer Documentation

Apple's modern SwiftUI patterns (WWDC 2023-2025) center on:

1. @Observable for data models (replaces ObservableObject)
2. State-as-Bridge for async boundaries (WWDC 2025)
3. Three property wrappers: @State, @Environment, @Bindable
4. Synchronous UI updates for animations

The State-as-Bridge Pattern

Problem

Async functions create suspension points that can break animations:

// ❌ Problematic: Animation might miss frame deadline
struct ColorExtractorView: View {
    @State private var isLoading = false

    var body: some View {
        Button("Extract Colors") {
            Task {
                isLoading = true  // Synchronous ✅
                await extractColors()  // ⚠️ Suspension point!
                isLoading = false  // ❌ Might happen too late
            }
        }
        .scaleEffect(isLoading ? 1.5 : 1.0)  // ⚠️ Animation timing uncertain
    }
}

Solution: Use State as a Bridge

"Find the boundaries between UI code that requires time-sensitive changes, and long-running async logic."

// ✅ Correct: State bridges UI and async code
@Observable
class ColorExtractor {
    var isLoading = false
    var colors: [Color] = []

    func extract(from image: UIImage) async {
        // This method is async and can live in the model
        let extracted = await heavyComputation(image)
        // Synchronous mutation for UI update
        self.colors = extracted
    }
}

struct ColorExtractorView: View {
    let extractor: ColorExtractor

    var body: some View {
        Button("Extract Colors") {
            // Synchronous state change for animation
            withAnimation {
                extractor.isLoading = true
            }

            // Launch async work
            Task {
                await extractor.extract(from: currentImage)

                // Synchronous state change for animation
                withAnimation {
                    extractor.isLoading = false
                }
            }
        }
        .scaleEffect(extractor.isLoading ? 1.5 : 1.0)
    }
}

Benefits:

• UI logic stays synchronous (animations work correctly)
• Async code lives in the model (testable without SwiftUI)
• Clear boundary between time-sensitive UI and long-running work

Property Wrapper Decision Tree

There are only 3 questions to answer:

Which property wrapper should I use?
│
├─ Does this model need to be STATE OF THE VIEW ITSELF?
│  └─ YES → Use @State
│     Examples: Form inputs, local toggles, sheet presentations
│     Lifetime: Managed by the view's lifetime
│
├─ Does this model need to be part of the GLOBAL ENVIRONMENT?
│  └─ YES → Use @Environment
│     Examples: User account, app settings, dependency injection
│     Lifetime: Lives at app/scene level
│
├─ Does this model JUST NEED BINDINGS?
│  └─ YES → Use @Bindable
│     Examples: Editing a model passed from parent
│     Lightweight: Only enables $ syntax for bindings
│
└─ NONE OF THE ABOVE?
   └─ Use as plain property
      Examples: Immutable data, parent-owned models
      No wrapper needed: @Observable handles observation

Examples

// ✅ @State — View owns the model
struct DonutEditor: View {
    @State private var donutToAdd = Donut()  // View's own state

    var body: some View {
        TextField("Name", text: $donutToAdd.name)
    }
}

// ✅ @Environment — App-wide model
struct MenuView: View {
    @Environment(Account.self) private var account  // Global

    var body: some View {
        Text("Welcome, \(account.userName)")
    }
}

// ✅ @Bindable — Need bindings to parent-owned model
struct DonutRow: View {
    @Bindable var donut: Donut  // Parent owns it

    var body: some View {
        TextField("Name", text: $donut.name)  // Need binding
    }
}

// ✅ Plain property — Just reading
struct DonutRow: View {
    let donut: Donut  // Parent owns, no binding needed

    var body: some View {
        Text(donut.name)  // Just reading
    }
}

@Observable Model Pattern

Use @Observable for business logic that needs to trigger UI updates:

// ✅ Domain model with business logic
@Observable
class FoodTruckModel {
    var orders: [Order] = []
    var donuts = Donut.all

    var orderCount: Int {
        orders.count  // Computed properties work automatically
    }

    func addDonut() {
        donuts.append(Donut())
    }
}

// ✅ View automatically tracks accessed properties
struct DonutMenu: View {
    let model: FoodTruckModel  // No wrapper needed!

    var body: some View {
        List {
            Section("Donuts") {
                ForEach(model.donuts) { donut in
                    Text(donut.name)  // Tracks model.donuts
                }
                Button("Add") {
                    model.addDonut()
                }
            }
            Section("Orders") {
                Text("Count: \(model.orderCount)")  // Tracks model.orders
            }
        }
    }
}

How it works (WWDC 2023/10149):

• SwiftUI tracks which properties are accessed during body execution
• Only those properties trigger view updates when changed
• Granular dependency tracking = better performance

ViewModel Adapter Pattern

Use ViewModels as presentation adapters when you need filtering, sorting, or view-specific logic:

// ✅ ViewModel as presentation adapter
@Observable
class PetStoreViewModel {
    let petStore: PetStore  // Domain model
    var searchText: String = ""

    // View-specific computed property
    var filteredPets: [Pet] {
        guard !searchText.isEmpty else { return petStore.myPets }
        return petStore.myPets.filter { $0.name.contains(searchText) }
    }
}

struct PetListView: View {
    @Bindable var viewModel: PetStoreViewModel

    var body: some View {
        List {
            ForEach(viewModel.filteredPets) { pet in
                PetRowView(pet: pet)
            }
        }
        .searchable(text: $viewModel.searchText)
    }
}

When to use a ViewModel adapter:

• Filtering, sorting, grouping for display
• Formatting for presentation (but NOT heavy computation)
• View-specific state that doesn't belong in domain model
• Bridging between domain model and SwiftUI conventions

When NOT to use a ViewModel:

• Simple views that just display model data
• Logic that belongs in the domain model
• Over-extraction just for "pattern purity"

---

Part 2: MVVM Pattern

When to Use MVVM

MVVM (Model-View-ViewModel) is appropriate when:

✅ You're familiar with it from UIKit — Easier onboarding for team ✅ You want explicit View/ViewModel separation — Clear contracts ✅ You have complex presentation logic — Multiple filtering/sorting operations ✅ You're migrating from UIKit — Familiar mental model

❌ Avoid MVVM when:

• Views are simple (just displaying data)
• You're starting fresh with SwiftUI (Apple's patterns are simpler)
• You're creating unnecessary abstraction layers

MVVM Structure for SwiftUI

// Model — Domain data and business logic
struct Pet: Identifiable {
    let id: UUID
    var name: String
    var kind: Kind
    var trick: String
    var hasAward: Bool = false

    mutating func giveAward() {
        hasAward = true
    }
}

// ViewModel — Presentation logic
@Observable
class PetListViewModel {
    private let petStore: PetStore

    var pets: [Pet] { petStore.myPets }
    var searchText: String = ""
    var selectedSort: SortOption = .name

    var filteredSortedPets: [Pet] {
        let

---

*Content truncated.*