SwiftUI Architecture

Use this skill for new SwiftUI apps, new features, and architecture reviews.

When not to use

• Single-screen prototypes → prefer simple MVVM.
• Projects committed to TCA, VIPER, or other architectures unless explicitly migrating.

Architecture decision table

Use the smallest structure that keeps responsibilities clear.

The preferred default for a feature with business rules is View → ViewModel → focused UseCase(s). When a UseCase crosses an infrastructure boundary—such as persistence, networking, files, StoreKit, analytics, or device APIs—it depends on a narrow Manager protocol. Features without infrastructure do not need a Manager layer. Add a Factory when construction or implementation selection is genuinely complex. Use simple View → ViewModel for screens whose behavior is only local presentation state; do not add empty layers to match the default.

Core feature boundary

One main feature View → exactly one owning ViewModel. When the feature has business operations, that ViewModel may depend on one or more focused UseCase protocols.

The one-ViewModel rule does not mean one UseCase. When the same feature needs profile, purchase, or preference operations, inject the relevant focused UseCase protocols into its existing ViewModel. Do not add another ViewModel or merge unrelated UseCases just to serve that feature. A simple screen may have no UseCase at all.

Closures support component actions, presentation events, and content composition. Keep callback APIs small and purposeful; do not use closures to conceal forbidden dependencies, move business workflows into Views, or forward actions through layers of otherwise unnecessary containers. See closure boundaries.

Non-negotiable rules

1. Unidirectional dependencies:
   • Runtime flow is View → ViewModel → UseCase → Manager when those layers are present; simple presentation-only features may stop at ViewModel.
   • App wires dependencies and owns shared lifetimes; factories create individual instances from supplied dependencies.
2. Protocol-first at boundaries: Use protocols for replaceable infrastructure and business dependencies. A trivial private implementation does not need a protocol solely to satisfy this guide.
3. ViewModels own UI state on @MainActor. Prefer @Observable when the app targets iOS 17/macOS 14 or later and its toolchain supports Observation; for earlier targets, use the app's compatible ObservableObject approach. Preserve existing observation conventions unless migration is requested. Use a nested ViewState enum when mutually exclusive screen modes make it clearer. Independent state such as drafts, selection, sheets, and alerts may remain separate properties. See observation and deployment targets.
4. ViewModels depend on focused UseCase protocols when business operations require them — never managers or other ViewModels. Each UseCase depends directly on the narrow manager protocols it needs, never another UseCase.
5. Views have explicit roles — each feature View receives exactly one owning feature ViewModel. Composition views may receive multiple child ViewModels to assemble independent features using instances supplied by App. Reusable visual components receive values, bindings, and action closures. Views do not call UseCases, perform business operations, or create business services. Scoped navigation state is a presentation exception: feature/composition Views may access it; ViewModels and UseCases may not. ViewModels expose operation results and UI state, not routes or navigation commands; Views decide how to navigate. See navigation and lifetimes.
6. Factories create individual instances — each method creates one Manager, UseCase, or ViewModel and accepts its dependencies as arguments. Start with one factory; split by domain or platform when current complexity warrants it. Names such as Factory, AppFactory, and [Domain]Factory are conventions, not architectural requirements. Platform implementation selection is allowed; business logic and hidden feature/application graphs are forbidden.
7. Recommend-first: Propose folder tree + types before creating files.
8. Comments explain intent, not syntax: Do not add comments that restate an obvious declaration, method name, property name, or control flow. Add comments when they document a non-obvious invariant, ownership decision, platform workaround, concurrency constraint, public API contract, or follow-up requirement. Prefer clear names and structure over explanatory narration.

Architecture review workflow

Use this mode when the user asks to review, audit, inspect, or give feedback on an existing project.

1. Inspect the existing folder structure, target boundaries, representative Views, ViewModels, UseCases, Managers, factories, and navigation wiring before recommending changes.
2. Trace actual dependencies from the composition root through a feature. Do not infer a violation from a filename or folder name alone.
3. Report findings with file paths and symbols when possible. Separate required corrections, recommendations, and contextual options.
4. Explain the smallest change that would resolve each required correction and identify any affected lifetime or isolation boundary.
5. Do not create files, restructure the project, add abstractions, run tests, or run builds during a review unless the user separately requests implementation or verification.
6. End with a prioritized list of reviewable changes. If the user approves a specific item, implement only that item and preserve earlier approved decisions.

Review mode is evidence-first: existing code and the user's stated project contract take precedence over generic examples in this skill.

During review, flag comments that merely narrate obvious code and remove them only when implementation is requested. Preserve comments that explain why the code must remain unusual.

Model ownership

Treat domain, presentation, and persistence models as suggested responsibility categories, not a mandatory three-type structure. Reuse plain domain values across Managers, UseCases, ViewModels, and Views when their meaning matches. Separate persistence/transport/UI representations only when their requirements differ. Keep framework-managed records and contexts inside their owning integration; business-facing APIs expose domain values or identifiers. See model ownership for placement and conversion rules.

Scaffold workflow

Before choosing observation or navigation APIs, inspect the project's minimum OS versions and Swift toolchain. Preserve its supported targets; adapt examples rather than raising deployment targets to fit them.

Phase 1 — Propose (no file creation)

1. Confirm feature name and domain (e.g. Catalog / ItemList).

2. List files to add under:

   • Pages/
   • Factory/ (only if creation/selection complexity warrants it)
   • Manager/ (only if infrastructure is needed)
   • UseCase/ (only if business operations need a separate boundary)
   • Component/ (only when UI is shared)
   • Constants/
   • Utility/

   Adapt roots to the project's existing layout.

3. Output:
   • Folder tree
   • Protocol names per layer
   • Dependency graph for the layers that actually exist
   • ViewState cases only if an enum improves the feature's state model
4. Stop and ask for approval unless the user has already approved this implementation scope in the current conversation.

Phase 2 — Implement (after approval)

5. Create protocols before implementations.
6. Wire the composition root in App, calling factories for individual instances.
7. ViewModel + View last.
8. Extract shared UI to Component/ only when used by 2+ features.

New feature checklist (short)

• Factory — only if creation/selection complexity warrants it; reuse existing factories
• Manager — only if the feature needs infrastructure; use a protocol when replaceability/test seams matter
• UseCases — only for focused business operations that need a separate boundary
• ViewModel — [Feature]ViewModel; add ViewState when mutually exclusive modes benefit from it
• ViewModel observation matches deployment target and existing conventions; injected ViewModel lifetime is explicit
• View — [Feature]View receives one owning ViewModel; compose independent features without an aggregate ViewModel
• DI wired in App; shared manager instances created once and reused

Layer quick reference

Testing guidance

• UseCase tests: when a UseCase exists, mock its Manager protocols and verify business rules and orchestration.
• ViewModel tests: mock injected UseCase protocols when present; verify state transitions and user-intent handlers.
• View tests: use previews or snapshot-style checks when they provide value; keep Views thin and deterministic.

Migration guidance

If adopting this architecture in an existing codebase:

• Existing MVVM: introduce a UseCase when business logic grows beyond UI state shaping.
• ViewModel calling managers directly: wrap manager calls behind a UseCase protocol; ViewModel depends on the relevant UseCase protocols only.
• Factory migration: keep individual creation methods in appropriately scoped factories. Move graph assembly and shared-instance ownership into App; replace hidden feature builders one feature at a time. Do not consolidate focused factories merely to enforce a single factory.
• ViewModel or UseCase chains: remove ViewModel → ViewModel and UseCase → UseCase dependencies. Inject focused UseCases into the owning ViewModel; keep business workflows inside a focused UseCase operating directly on manager protocols.

Anti-patterns (reject if suggested)

// BAD — ViewModel → Manager
final class ItemListViewModel {
    private let fileManager = FileSystemManager()
}

// GOOD
final class ItemListViewModel {
    private let useCase: ItemListUseCaseProtocol
}

// BAD — View → UseCase
Button("Load") { Task { await useCase.load() } }

// GOOD
Button("Load") { Task { await viewModel.load() } }

Additional resources

Read only what you need:

• Layer overview
• Folder structure
• Model ownership and persistence boundaries
• Dependency flow
• Naming conventions
• New feature checklist
• Anti-patterns
• Navigation and dependency lifetimes
• Concurrency
• Observation and deployment targets
• For deep Swift 6 concurrency diagnostics and migration, use the companion Swift Concurrency Agent Skill.
• End-to-end example