Swiftui Data Flow Expert

---
license: Apache-2.0
name: swiftui-data-flow-expert
description: "SwiftUI data flow expert with @Observable, SwiftData, NavigationStack, and structured concurrency. Activate on: SwiftUI state management, @Observable, SwiftData, NavigationStack, Combine, async/await Swift, structured concurrency, MVVM SwiftUI. NOT for: UIKit legacy (use react-native-architect), Core Data migrations (use ios-core-data-architect), Android Compose (use jetpack-compose-navigation-expert)."
allowed-tools: Read,Write,Edit,Bash(swift:*,xcodebuild:*)
category: Mobile Development
tags:
  - swiftui
  - ios
  - swift
  - state-management
pairs-with:
  - skill: native-app-designer
    reason: Native design patterns inform SwiftUI component architecture
  - skill: ios-core-data-architect
    reason: Core Data and SwiftData persistence layer beneath SwiftUI views
---

# SwiftUI Data Flow Expert

Expert in SwiftUI state management with @Observable, SwiftData persistence, NavigationStack, and structured concurrency patterns for iOS 17+/18.

## Decision Points

### State Management Choice

```
1. View-local state (form inputs, toggles, local UI)?
   → Use @State
   → Keep data inside the view
   → Example: @State private var showingSheet = false

2. Shared state across views (user session, app data)?
   → Use @Observable class
   → Pass via @Environment or init
   → Example: @Observable class UserSession

3. Persistent data (saved to disk)?
   → Use SwiftData @Model
   → Access via @Query in views
   → Example: @Model class Expense

4. External data source (network, sensors)?
   → Use @Observable + async methods
   → Wrap in Task {} for concurrency
   → Example: @Observable class WeatherViewModel
```

### Concurrency Model Choice

```
1. Single async operation (network call)?
   → Use Task {} in SwiftUI .task modifier
   → Handle errors with do/catch

2. Multiple related operations?
   → Use TaskGroup for parallel execution
   → Use await for sequential dependencies

3. Continuous data stream (location, sensors)?
   → Use AsyncStream or AsyncSequence
   → Cancel with .onDisappear

4. Background processing?
   → Use @globalActor or custom actor
   → Never access @MainActor data directly
```

### Data Binding Strategy

```
1. Direct property binding needed?
   → Use @Bindable(viewModel)
   → Allows $ syntax for Observable objects

2. One-way data flow only?
   → Pass Observable directly
   → Read properties without $

3. Computed property or transformation?
   → Create computed var in Observable class
   → SwiftUI auto-tracks changes

4. Form data with validation?
   → Use @State for working copy
   → Sync to Observable on save/submit
```

## Failure Modes

### Symptom: View Won't Re-render
- **Detection**: Data changes but UI stays stale
- **Diagnosis**: Missing observation or wrong binding type
- **Fix**: Ensure @Observable class, check @Bindable usage, verify property access

### Symptom: App Crashes on Navigation
- **Detection**: Fatal error on NavigationLink tap or back navigation
- **Diagnosis**: Type mismatch in NavigationStack routing
- **Fix**: Verify navigationDestination(for:) matches NavigationLink value types

### Symptom: Data Appears Then Disappears
- **Detection**: SwiftData @Query shows data briefly, then empty list
- **Diagnosis**: ModelContext not properly injected or predicate filtering all results
- **Fix**: Check .modelContainer() in App, verify @Query predicate syntax

### Symptom: Async Task Never Completes
- **Detection**: Loading spinner forever, no error thrown
- **Diagnosis**: Task not cancelled on view dismiss, holding strong references
- **Fix**: Store Task reference, call .cancel() in .onDisappear, check actor isolation

### Symptom: Main Thread Blocking
- **Detection**: UI freezes during operations, Xcode warnings about main actor
- **Diagnosis**: Heavy work or synchronous I/O on main thread
- **Fix**: Wrap in Task {}, use @globalActor for background work, check Sendable conformance

## Worked Examples

### Complete Order Management Flow

**Scenario**: Build order list with SwiftData persistence, async loading, and type-safe navigation.

**Step 1: Define the data model**
```swift
@Model
class Order {
    var id: UUID
    var customerName: String
    var total: Decimal
    var status: OrderStatus
    var createdAt: Date
    
    init(customerName: String, total: Decimal) {
        self.id = UUID()
        self.customerName = customerName
        self.total = total
        self.status = .pending
        self.createdAt = .now
    }
}
```

**Step 2: Navigation routing (expert catches type safety)**
```swift
enum AppRoute: Hashable {
    case orderDetail(Order.ID)  // UUID, not Order object
    case newOrder
}
```

**Step 3: Observable view model for business logic**
```swift
@Observable
class OrderStore {
    var isLoading = false
    var error: AppError?
    
    @MainActor
    func syncWithServer(context: ModelContext) async {
        isLoading = true
        defer { isLoading = false }
        
        do {
            let serverOrders = try await APIClient.shared.fetchOrders()
            // Update SwiftData context
            for serverOrder in serverOrders {
                context.insert(serverOrder.toModelObject())
            }
            try context.save()
        } catch {
            self.error = .sync(error)
        }
    }
}
```

**Step 4: SwiftUI view with decision points applied**
```swift
struct OrderListView: View {
    @Query(sort: \Order.createdAt, order: .reverse) private var orders: [Order]
    @Environment(\.modelContext) private var modelContext
    @State private var orderStore = OrderStore()
    @State private var path = NavigationPath()
    
    var body: some View {
        NavigationStack(path: $path) {
            List(orders) { order in
                NavigationLink(value: AppRoute.orderDetail(order.id)) {
                    OrderRow(order: order)
                }
            }
            .navigationTitle("Orders")
            .toolbar {
                Button("Add") { path.append(AppRoute.newOrder) }
                Button("Sync", action: sync)
            }
            .navigationDestination(for: AppRoute.self) { route in
                switch route {
                case .orderDetail(let id):
                    OrderDetailView(orderId: id)
                case .newOrder:
                    NewOrderView()
                }
            }
            .overlay {
                if orderStore.isLoading { ProgressView() }
            }
            .task { await sync() }
        }
    }
    
    private func sync() async {
        await orderStore.syncWithServer(context: modelContext)
    }
}
```

**Novice mistakes this catches:**
- Using Order object in navigation (crashes on back navigation)
- Missing @MainActor on UI updates from async context
- Not cancelling tasks on view disappear
- Using @State for shared business logic instead of @Observable

## Quality Gates

- [ ] All @Observable classes used for shared state (not @State)
- [ ] @Query sorts applied with explicit descriptors
- [ ] NavigationStack uses value-based routing (not destination-based)
- [ ] All async tasks properly cancelled on view disappear
- [ ] @MainActor respected for UI updates from background contexts
- [ ] SwiftData ModelContext injected via environment (not global)
- [ ] Error handling present for all async operations
- [ ] @Bindable used only when $ binding syntax needed
- [ ] No force unwrapping in production paths
- [ ] Sendable conformance for types crossing actor boundaries

## NOT-FOR Boundaries

**Do NOT use this skill for:**
- **UIKit/AppKit** → Use `ios-uikit-architect` for legacy UI frameworks
- **Core Data migrations** → Use `ios-core-data-architect` for existing Core Data stacks
- **Combine publishers** → Use `ios-reactive-architect` for existing Combine codebases
- **Cross-platform** → Use `flutter-architect` or `react-native-architect`
- **SwiftUI iOS 15/16** → Use `ios-legacy-swiftui` for pre-@Observable patterns
- **Performance optimization** → Use `ios-performance-engineer` for Instruments analysis
- **App Store deployment** → Use `ios-release-engineer` for CI/CD and signing

**Delegate to other skills when:**
- Complex animations needed → `native-app-designer`
- Backend integration → `api-integration-specialist`
- Testing strategies → `ios-test-architect`