# Ios Architecture

> >

- **Type:** Skill
- **Install:** `agentstack add skill-koshkinvv-ios-agent-skills-ios-architecture`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [koshkinvv](https://agentstack.voostack.com/s/koshkinvv)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [koshkinvv](https://github.com/koshkinvv)
- **Source:** https://github.com/koshkinvv/ios-agent-skills/tree/main/skills/ios-architecture

## Install

```sh
agentstack add skill-koshkinvv-ios-agent-skills-ios-architecture
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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.
9. **One ViewModel per screen** (not per view). Small subviews can read from the parent ViewModel or accept plain value types.
10. **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](https://github.com/koshkinvv)
- **Source:** [koshkinvv/ios-agent-skills](https://github.com/koshkinvv/ios-agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-koshkinvv-ios-agent-skills-ios-architecture
- Seller: https://agentstack.voostack.com/s/koshkinvv
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.