swift-ui-architect

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: swift-ui-architect
description: Opinionated SwiftUI architecture enforcement for iOS 26 / Swift 6.2 clinic modular MVVM-C apps using local SPM package boundaries. Enforces App-target `DependencyContainer` + route shells, @Observable ViewModels/coordinators, Domain repository/coordinator/error-routing protocols, Data-owned I/O, stale-while-revalidate reads, and optimistic queued sync. Use when writing, reviewing, or refactoring SwiftUI architecture, navigation, dependency wiring, or repository boundaries.
---

# SwiftUI Modular MVVM-C Architecture

Opinionated architecture enforcement for SwiftUI clinic-style apps. This skill aligns to the iOS 26 / Swift 6.2 clinic architecture: modular MVVM-C in local SPM packages, concrete coordinators and route shells in the App target, pure Domain protocols, and Data as the only I/O layer.

## Mandated Architecture Stack

```
┌───────────────────────────────────────────────────────────────┐
│ App target: DependencyContainer, Coordinators, Route Shells   │
├───────────────┬───────────────┬───────────────┬──────────────┤
│ Feature* SPM  │ Feature* SPM  │ Feature* SPM  │ Feature* SPM │
│ View + VM     │ View + VM     │ View + VM     │ View + VM    │
├───────────────────────────────────────────────────────────────┤
│ Data SPM: repository impls, remote/local, retry, sync queue   │
├───────────────────────────────────────────────────────────────┤
│ Domain SPM: models, repository protocols, coordinator protocols│
│ and ErrorRouting/AppError                                      │
├───────────────────────────────────────────────────────────────┤
│ Shared SPMs: DesignSystem, SharedKit                           │
└───────────────────────────────────────────────────────────────┘
```

**Dependency Rule**: Feature modules import `Domain` + `DesignSystem` only. Features never import `Data` or other features. App target is the only convergence point.


## Clinic Architecture Contract (iOS 26 / Swift 6.2)

All guidance in this skill assumes the clinic modular MVVM-C architecture:

- Feature modules import `Domain` + `DesignSystem` only (never `Data`, never sibling features)
- App target is the convergence point and owns `DependencyContainer`, concrete coordinators, and Route Shell wiring
- `Domain` stays pure Swift and defines models plus repository, `*Coordinating`, `ErrorRouting`, and `AppError` contracts
- `Data` owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
- Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
- ViewModels call repository protocols directly (no default use-case/interactor layer)

## When to Apply

Reference these guidelines when:
- Building or refactoring feature modules under local SPM packages
- Wiring coordinators, route shells, and dependency container factories
- Defining Domain protocols for repositories, coordinators, and error routing
- Enforcing Data-only ownership of networking, persistence, and sync
- Reviewing stale-while-revalidate reads and optimistic queued writes

## Non-Negotiable Constraints (iOS 26 / Swift 6.2)

- `@Observable` for ViewModels/coordinators, `ObservableObject` / `@Published` never
- No dedicated use-case/interactor layer: ViewModels call Domain repository protocols directly
- Coordinator protocols live in Domain; concrete coordinators own `NavigationPath` in App target
- Route shells live in App target and own `.navigationDestination` mapping
- `AppError` + `ErrorRouting` drive presentation policy; ViewModels do not hardcode global error UI
- SwiftData / URLSession / retry / sync queue logic stays in Data package only

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | View Identity & Diffing | CRITICAL | `diff-` | 6 |
| 2 | State Architecture | CRITICAL | `state-` | 7 |
| 3 | View Composition | HIGH | `view-` | 6 |
| 4 | Navigation & Coordination | HIGH | `nav-` | 5 |
| 5 | Layer Architect