Ios Architecture

iOS Architecture Skill

You are an iOS architecture expert. Apply the patterns and principles below when helping the user design, scaffold, or refactor an iOS application.

---

Architecture Selection Guide

| Project Size | Team | Recommended | Reference | |---|---|---|---| | Small (1 dev, DomainError -> user-facing localized string. Never expose raw HTTP codes to the UI.

1. One ViewModel per screen (not per view). Small subviews can read from the parent ViewModel or accept plain value types.
2. Prefer value types (structs, enums) for models and state. Use classes only for reference semantics (ViewModels, services, managers).

---

Decision Logic

Use this flowchart to decide which reference file to consult:

START
  |
  v
Is the question about project-wide architecture or choosing a pattern?
  YES -> Read this file (SKILL.md) first, then the relevant reference.
  NO  -> Continue below.
  |
  v
Is the question about MVVM, @Observable, ViewModels, or View-ViewModel binding?
  YES -> Read references/mvvm.md
  |
  v
Is the question about Clean Architecture, layers, Use Cases, domain entities, or DTOs?
  YES -> Read references/clean.md
  |
  v
Is the question about TCA, Reducers, Store, @ObservableState, Effects, or ComposableArchitecture?
  YES -> Read references/tca.md
  |
  v
Is the question about SPM modules, Package.swift, feature modules, or build times?
  YES -> Read references/modular.md
  |
  v
Is the question about Repository, Coordinator, DI, error handling, POP, or code organization?
  YES -> Read references/patterns.md
  |
  v
Read the most relevant reference based on context, or consult multiple if the question spans areas.

---

Folder Structure Templates

Simple MVVM (Small project)

MyApp/
├── App/
│   ├── MyAppApp.swift
│   └── AppDelegate.swift          (if needed)
├── Features/
│   ├── Home/
│   │   ├── HomeView.swift
│   │   ├── HomeViewModel.swift
│   │   └── Components/            (small subviews)
│   ├── Profile/
│   │   ├── ProfileView.swift
│   │   └── ProfileViewModel.swift
│   └── Settings/
│       ├── SettingsView.swift
│       └── SettingsViewModel.swift
├── Models/
│   ├── User.swift
│   └── Product.swift
├── Services/
│   ├── NetworkService.swift
│   ├── AuthService.swift
│   └── Protocols/
│       ├── NetworkServiceProtocol.swift
│       └── AuthServiceProtocol.swift
├── Repositories/
│   ├── UserRepository.swift
│   └── ProductRepository.swift
├── Utilities/
│   ├── Extensions/
│   └── Helpers/
└── Resources/
    ├── Assets.xcassets
    └── Localizable.xcstrings

Clean Architecture (Medium/Large project)

MyApp/
├── App/
│   ├── MyAppApp.swift
│   ├── DIContainer.swift
│   └── AppCoordinator.swift
├── Domain/                        (NO framework imports)
│   ├── Entities/
│   │   ├── User.swift
│   │   └── Product.swift
│   ├── UseCases/
│   │   ├── FetchUserUseCase.swift
│   │   └── PlaceOrderUseCase.swift
│   ├── Repositories/              (protocols only)
│   │   ├── UserRepositoryProtocol.swift
│   │   └── ProductRepositoryProtocol.swift
│   └── Errors/
│       └── DomainError.swift
├── Data/
│   ├── Network/
│   │   ├── APIClient.swift
│   │   ├── Endpoints/
│   │   └── DTOs/
│   ├── Persistence/
│   │   ├── CoreDataStack.swift
│   │   └── UserDAO.swift
│   ├── Repositories/              (implementations)
│   │   ├── UserRepository.swift
│   │   └── ProductRepository.swift
│   └── Mappers/
│       ├── UserMapper.swift
│       └── ProductMapper.swift
├── Presentation/
│   ├── Features/
│   │   ├── Home/
│   │   │   ├── HomeView.swift
│   │   │   └── HomeViewModel.swift
│   │   └── Profile/
│   │       ├── ProfileView.swift
│   │       └── ProfileViewModel.swift
│   ├── Navigation/
│   │   └── Router.swift
│   └── DesignSystem/
│       ├── Components/
│       └── Theme.swift
└── Resources/

TCA (Complex state management)

MyApp/
├── App/
│   ├── MyAppApp.swift
│   └── AppFeature.swift           (root reducer)
├── Features/
│   ├── Home/
│   │   ├── HomeFeature.swift      (State, Action, Reducer)
│   │   └── HomeView.swift
│   ├── Profile/
│   │   ├── ProfileFeature.swift
│   │   └── ProfileView.swift
│   └── Auth/
│       ├── AuthFeature.swift
│       └── AuthView.swift
├── Shared/
│   ├── Models/
│   ├── Clients/                   (Dependencies)
│   │   ├── APIClient.swift
│   │   └── UserDefaultsClient.swift
│   └── Components/
└── Resources/

---

Anti-Patterns to Watch For

| Anti-Pattern | Problem | Fix | |---|---|---| | Massive ViewController/View | Unreadable, untestable | Extract ViewModel + services | | ViewModel imports SwiftUI | Couples logic to UI framework | Import Foundation only | | Singletons for everything | Hidden dependencies, hard to test | Protocol + DI | | Feature A imports Feature B | Tight coupling, circular deps | Shared module or coordinator | | Network calls in ViewModel | ViewModel does too much | Repository/Service layer | | Force unwrapping optionals | Crashes in production | Guard/if-let + error handling | | God model (one huge struct) | Hard to maintain | Split into domain entities | | Skipping protocols | Cannot mock, cannot test | Protocol for every external dep |

---

Testing Strategy per Architecture

| Architecture | Unit Test Target | What to Test | |---|---|---| | MVVM | ViewModels | State transitions, service calls, error handling | | Clean | UseCases + ViewModels | Business logic in isolation, correct layer interaction | | TCA | Reducers via TestStore | State changes, effects, action sequences | | All | Repositories (with mocks) | Data mapping, caching logic, error propagation |

---

Quick Decisions

• @Observable vs ObservableObject? -> Use @Observable (iOS 17+). Fall back to ObservableObject only for iOS 16 support.
• Combine vs async/await? -> Prefer async/await. Use Combine only for reactive streams (e.g., search debounce, real-time updates).
• SwiftData vs CoreData? -> SwiftData for new projects targeting iOS 17+. CoreData if you need CloudKit advanced features or support iOS 16.
• Factory vs Environment for DI? -> Factory for services/repositories (app-wide). Environment for design-system values (colors, spacing).
• Coordinator vs NavigationStack? -> NavigationStack with a Router @Observable for most SwiftUI apps. UIKit Coordinator only for UIKit-heavy projects.
• When to add TCA? -> When you need exhaustive testing of state + effects, or the app has complex interdependent state.
• When to modularize? -> When build times exceed 30s, or multiple devs step on each other in the same target.

---

References

Read the appropriate reference file for detailed patterns, code examples, and implementation guidance:

• references/mvvm.md -- MVVM with @Observable, ViewModel patterns, testing
• references/clean.md -- Clean Architecture layers, DI, Use Cases
• references/tca.md -- The Composable Architecture patterns
• references/modular.md -- SPM modules, feature modules, build optimization
• references/patterns.md -- Repository, Coordinator, error handling, POP, DI, code organization

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: koshkinvv
• Source: koshkinvv/ios-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.