Uikit Mvvm

---
name: uikit-mvvm
description: "Use for hands-on UIKit MVVM questions: setting up Combine bindings between UIViewController and ViewModel (@Published + sink), extracting business logic from massive ViewControllers step by step, testing ViewModels with XCTestExpectation + Combine publishers, fixing [weak self] retain cycles in sink closures, migrating DispatchQueue/GCD completion handlers to Combine, or replacing reloadData() with DiffableDataSource. Also covers Coordinator navigation patterns, constructor injection, ViewState enum, and incremental MVC-to-MVVM refactoring. Trigger on any UIKit architecture decision — even when the user doesn't mention 'MVVM' explicitly."
metadata:
  version: 1.0.4
---

> **Approach: Production-First Iterative Refactoring** — This skill is built for production enterprise codebases where stability and reviewability matter more than speed. Architecture changes are delivered through iterative refactoring — small, focused PRs (≤200 lines, single concern) tracked in a `refactoring/` directory. Critical safety issues ship first; cosmetic improvements come last.

# UIKit MVVM Architecture (iOS 13+)

Enterprise-grade UIKit MVVM architecture skill. Opinionated: prescribes Combine-bound ViewModels, Coordinator navigation, constructor injection via factories, ViewState enum, DiffableDataSource, and programmatic Auto Layout. Adopts a **production-first iterative refactoring** approach — every pattern is chosen for testability, reviewability, and safe incremental adoption in large teams. UIKit MVVM remains the dominant production architecture for large-scale iOS apps.

## Architecture Layers

```text
View/ViewController  → UIViewController + UIView. Binds to ViewModel via Combine/closures/GCD. Renders state.
ViewModel Layer      → Zero UIKit imports. Exposes ViewState<T>. Uses @Published (Combine) or closures (GCD).
Coordinator Layer    → Manages navigation flow. Creates ViewModels + VCs. Owns UINavigationController.
Repository Layer     → Protocol-based data access. Hides data source details.
Service Layer        → URLSession, persistence. Injected via protocol. May use GCD or async/await.
```

## Quick Decision Trees

### "Should this ViewController have a ViewModel?"

```
Is there business logic, networking, or complex state?
├── YES → Create a ViewModel (see "Which binding mechanism" below for Combine vs closures)
└── NO → Is it a container/flow controller (tab bar, navigation)?
    ├── YES → Coordinator manages it, no ViewModel needed
    └── NO → No ViewModel needed unless it simplifies testing
```

### "Which binding mechanism should I use?"

```text
Is this a legacy codebase with heavy GCD / completion handlers?
├── YES → Is the goal to extract ViewModels first (keep GCD)?
│   ├── YES → Closures / Bindable<T> + GCD in service layer
│   │   └── Upgrade to Combine later (see migration-patterns.md)
│   └── NO → Adopt Combine during extraction
│       └── @Published + sink (production standard)
└── NO → What is the minimum iOS target?
    ├── iOS 13+ → Combine: @Published + sink
    │   └── One-shot events? → PassthroughSubject
    └── < iOS 13 → Closures / Bindable<T> wrapper
```

### "Where do dependencies come from?"

```
ViewModel always receives dependencies via constructor:
  init(service: NetworkServiceProtocol)

Who creates the ViewModel?
├── Coordinator (recommended)
│   └── Coordinator owns factory, creates VM with deps, passes to VC init
├── VC creates it (simpler apps)
│   └── VC receives deps via init, passes to VM init
└── DI Container (large apps, 20+ screens)
    └── Container resolves protocols, coordinator pulls from container
```

### "How should I handle navigation?"

```
Is there more than one navigation flow (auth + main, tabs)?
├── YES → Coordinator pattern with parent/child hierarchy
│   └── AppCoordinator → AuthCoordinator / MainCoordinator → TabCoordinator
└── NO → Single Coordinator wrapping UINavigationController
    └── ViewModel signals navigation via closures, never UIKit imports
```

## Workflows

> **Default workflow**: Analyze & Refactor (below). New screen creation applies the same patterns but from a clean slate. In production enterprise codebases, most work is iterative modernization — not greenfield.

### Workflow: Analyze & Refactor Existing MVC Codebase

**When:** First encounter with a legacy UIKit MVC codebase — the most common enterprise scenario.

1. Scan for anti-patterns using the detection checklist (`references/anti-patterns.md`)
2. Create `refactoring/` directory with per-feature plan files (`references/refactoring-workflow.md`)
3. Write each issue with **full description** (Location, Severity, Problem, Fix) — titles alone get forgotten
4. Categorize issues by severity: 🔴 Critical → 🟡 High → 🟢 Medium
5. Plan Phase 1 PR: fix critical safety issues only (≤200 lines per PR)
6. Execute one PR at a time. New findings go to `refactoring/discovered.md` with full descriptions, NOT into current PR
7. After completing each fix: mark the task `- [x]` and update the Progress table
8. Proceed through phases: Critical → ViewModel extraction → Coordinator → Combine bindings → DI

### Workflow: Create a New Screen

**When:** Building a new feature screen from scratch. Apply enterprise patterns from the start.

1. Define the data model and repository protocol (`references/testing.md` for mock pattern)
2. Create ViewModel: plain class with `private(set) var state: ViewState<T>` — zero UIKit imports (use `@Published` + Combine or closures per the binding mechanism decision tree)
3. Add `// MARK: -` sections: Properties, Init, Actions, Computed Properties
4. Create the ViewController with constructor injection: `init(viewModel: MyViewModel)`
5. Wire Combine bindings in `setupBindings()` called from `viewDidLoad`
6. Build UI programmatically with Auto Layout (`references/layout-approaches.md`)
7. Add Coordinator route and factory method (`references/coordinator-navigation.md`)
8. Create test file with mock repository (`references/testing.md`)

### Workflow: Extract ViewModel from Massive ViewController

**When:** Refactoring an existing MVC screen to MVVM incrementally.

1. Identify all state properties in the VC (data, loading flags, error state)
2. Create ViewModel class — move state properties to `@Published private(set) var`
3. Move business logic methods from VC to VM (networking, validation, formatting)
4. Add Combine `@Published` to VM state, `Set<AnyCancellable>` to VC
5. Replace direct state access in VC with `viewModel.$property.sink` bindings
6. Remove all `import UIKit` from ViewModel — compiler will flag violations
7. Write tests for the ViewModel (now possible since VM has no UIKit dependency)
8. Verify VC only does: bind, render, forward user actions to VM

### Workflow: Introduce Coordinators to Existing MVVM

**When:** Navigation is scattered across ViewControllers. Adding Coordinators incrementally.

1. Start with one flow (e.g., auth flow or a tab's navigation stack)
2. Create Coordinator protocol and AppCoordinator (`references/coordinator-navigation.md`)
3. Move VC creation from VCs/Storyboard segues to Coordinator's factory methods
4. Replace `performSegue` / `pushViewController` calls with ViewModel navigation closures
5. Wire Coordinator as `UINavigationControllerDelegate` for back-button cleanup
6. Add child coordinator lifecycle management (didFinish delegate pattern)
7. Test Coordinator with mock `UINavigationController` (`references/testing.md`)

## Code Generation Rules

<critical_rules>
Whether generating new code or refactoring existing code, every output must be **production-ready and PR-shippable** — small, focused, and testable. ALWAYS:

1. ViewModels import only `Foundation` and `Combine` — never `UIKit`
2. Use `@Published private(set) var` for state properties modified only by the ViewModel
3. Use `ViewState<T>` enum for async data — never separate boolean flags
4. Inject dependencies via constructor with protocol types
5. Bind in `viewDidLoad` using `setupBindings()` — store in `Set<AnyCancellable>`
6. Always `[weak self]` in `sink` closures when stored in `cancellables`
7. Always `.receive(on: DispatchQueue.main)` before UI updates in sink
8. Add `// MARK: -` sections: Properties, Init, Lifecycle, Bindings, Actions
9. Use programmatic Auto Layout — `translatesAutoresizingMaskIntoConstraints = false`
10. Keep every generated file ≤ 400 lines. Extract child VCs or ViewModel extensions when approaching that limit.
11. Before modifying a ViewController, output a brief `<thought>` analyzing its current dependencies and retain cycles.
</critical_rules>

When generating tests, ALWAYS:

1. Use protocol mocks with `var stubbed*` and `var *CallCount` tracking
2. Test through public interface, never test private methods
3. Use `XCTestExpectation` + `sink` + `dropFirst()` for Combine publisher tests
4. Use `await fulfillment(of:)` for async tests — NEVER `wait(for:)` in async contexts. When you write async test code in a response, the **actual code example must call `await fulfillment(of: [expectation], timeout: 2.0)`**, not `wait(for: [expectation], timeout: 2.0)`. Mentioning the modern API only in a note while the code uses `wait(for:)` still hangs the test — it's the classic cooperative-pool deadlock. In XCTestCase this is a synchronous blocking call that cannot pump the queue, so the expectation never fulfills:

```swift
// ❌ WRONG — deadlocks in async test function
func test_load_updates_items() async {
    let exp = expectation(description: "items updated")
    let cancellable = sut.$items.dropFirst().sink { _ in exp.fulfill() }
    await sut.load()
    wait(for: [exp], timeout: 2.0)  // cooperative-pool deadlock
    _ = cancellable
}

// ✅ CORRECT — releases the cooperative thread via await
func test_load_updates_items() async {
    let exp = expectation(description: "items updated")
    let cancellable = sut.$items.dropFirst().sink { _ in exp.fulfill() }
    await sut.load()
    await fulfillment(of: [exp], timeout: 2.0)
    _ = cancellable
}
```
5. Include memory leak detection with `addTeardownBlock { [weak sut] in XCTAssertNil(sut) }`

## Fallback Strategies & Loop Breakers

<fallback_strategies>
When refactoring legacy code, you may encounter stubborn Swift compiler errors. If you fail to fix the same error twice, break the loop:

1. **Combine Type Erasure:** If you get generic type mismatch errors with Combine `AnyPublisher`, append `.eraseToAnyPublisher()` to the pipeline or fall back to closures instead of fighting the type system. Why: Combine's generic types nest deeply (e.g., `Publishers.Map<Publishers.Filter<...>, Output>`), and type erasure is the standard solution.
2. **DiffableDataSource Generics:** If the compiler complains about `Hashable` conformance or type differences in `NSDiffableDataSourceSnapshot`, verify your `CellViewModel` uses a unique `UUID` instead of complex nested generic models. Why: DiffableDataSource compares items by hash — nested models with mutable state produce inconsistent hashes and silent data corruption.
3. **Revert and Restart:** If a ViewController refactor spirals into 50+ compiler errors, stop. Propose reverting the changes and breaking the problem into two smaller phases (e.g., extract networking first, then migrate state). Why: UIKit's implicit dependencies cascade — changing one property often breaks unrelated outlets, delegates, and data sources.
</fallback_strategies>

## Confidence Checks

Before finalizing generated or refactored code, verify ALL:

```
□ No duplicate functionality — searched codebase for existing implementations
□ Architecture adherence — follows patterns already established in the project
□ Naming conventions — matches existing project naming style
□ Import check — ViewModel imports only Foundation + Combine, NOT UIKit
□ ViewState — used for all async data, no separate isLoading/error booleans
□ Combine bindings — [weak self] in every sink, .receive(on: .main) before UI updates
□ DI — dependencies injected via protocol, not accessed via singletons
□ Coordinator — navigation handled by Coordinator, not by VC pushing other VCs
□ Memory management — deinit cancels Tasks, no retain cycles in closures
□ Tests — corresponding test file exists or is created alongside
□ PR scope — changes within defined scope, new findings go to `refactoring/discovered.md`
□ File size — new files ≤ 400 lines; existing oversized files have a split task logged
```

## Companion Skills

> **Before generating async ViewModel or migrating completion handlers:** determine the project's concurrency approach. If unclear from context, ask the user.

| Project's concurrency stack | Companion skill | Apply when |
|---|---|---|
| `async/await`, actors, Swift 6 (migrating or greenfield) | `skills/swift-concurrency/SKILL.md` | Migrating completion handlers, writing async ViewModel methods, actor-based state |
| `DispatchQueue`, `OperationQueue` (staying or auditing existing) | `skills/gcd-operations/SKILL.md` | Reviewing existing queue code, writing queue-based concurrency, thread-safe collections |
| Mixed (GCD stays, new code gets async/await) | Both skills | Apply GCD rules to existing code, concurrency rules to new code |

**If unclear, ask:** "Is the team migrating to Swift Concurrency or keeping GCD/OperationQueue?"

## References

| Reference | When to Read |
|-----------|-------------|
| `references/rules.md` | Do's and Don'ts quick reference: priority rules and critical anti-patterns |
| `references/binding-mechanisms.md` | Combine @Published + sink, closures, async/await, Input/Output pattern, decision matrix |
| `references/coordinator-navigation.md` | Coordinator protocol, hierarchy, memory management, back button handling, deep linking |
| `references/viewcontroller-lifecycle.md` | VC lifecycle, ViewState enum, DiffableDataSource, VC containment, keyboard handling |
| `references/dependency-injection.md` | Constructor injection, Factory pattern, Storyboard DI, Container/Resolver, @Injected wrapper |
| `references/layout-approaches.md` | Programmatic Auto Layout, UIStackView, XIBs, Storyboards, decision criteria |
| `references/testing.md` | Testing Combine publishers, async ViewModels, mocking, memory leak detection, Coordinator tests |
| `references/anti-patterns.md` | Code review detection checklist, severity-ranked UIKit MVVM violations |
| `references/migration-patterns.md` | MVC → MVVM, UIKit → SwiftUI, Combine adoption strategies |
| `references/refactoring-workflow.md` | `refactoring/` directory protocol, per-feature plans, PR sizing, phase ordering |
| `references/file-organization.md` | File size guidelines, ViewModel extension splits, child ViewControllers and subclassing views |