swift-architecture

Swift Architecture is a decision-support and code-review skill for selecting, reviewing, and migrating Apple-platform app architectures. Its guiding principle is to choose the smallest architecture that makes state ownership, dependencies, side effects, and tests explicit, defaulting new SwiftUI features to MV with the Observation framework and escalating only when observed complexity justifies it.

It covers a spectrum of patterns (MV, MVVM, MVI, TCA, Clean Architecture, Coordinator, and legacy VIPER) with a comparison table describing when to choose each and its main cost, plus explicit escalation signals for moving beyond MV. A five-step decision workflow has the user record the feature's state owner, inputs, dependencies, side effects, and tests; identify the concrete pressure (complex state machine, shared derived state, dependency control, feature composition, team ownership, or UIKit navigation); select the smallest fitting pattern; implement one vertical slice with injected dependencies; and validate with behavior, state-transition, and dependency-failure tests before migrating further. A references/architecture-patterns.md file provides concrete Swift structure recipes for each pattern, and the skill defines clear scope boundaries that route property-wrapper wiring, navigation APIs, concurrency isolation, and test syntax to sibling skills.

It targets iOS/macOS Swift and SwiftUI engineers and architects deciding module and dependency boundaries, escalating features, planning incremental migrations, or auditing state ownership and test seams. It is guidance and reference material rather than an automated code generator.