ios-app-architecture

Files (1)

• SKILL.md

SKILL.md (first lines)

# iOS App Architecture

Design for fast solo iteration, not architecture theater.

## Defaults

- SwiftUI first
- UIKit only where platform APIs require it
- small focused view files
- clear service boundaries
- view models without UI imports
- persistence decisions made early
- zero third-party dependencies by default

## Recommended Shape

- `App/`
  - app entry, container setup, navigation state, app delegates
- `Models/`
  - persistent models and small domain types
- `Services/`
  - business operations, persistence helpers, sync, export, OCR, billing
- `ViewModels/`
  - screen state and orchestration
- `Views/`
  - product UI, grouped by feature
- `Utilities/`
  - constants, theming, environment helpers
- `Intents/`, `Widgets/`, `Extensions/`
  - separate when the app actually needs them

## State Rules

- `View` owns display state
- `ViewModel` owns screen logic
- `Service` owns reusable operations
- avoid singletons unless the dependency is truly app-wide
- if something is cross-screen but UI-driven, make the ownership explicit

## Persistence Rules

- choose the store model early
- keep model types small and obvious
- avoid mixing persistence logic throughout views
- isolate migrations, seeding, and shared-container setup near app boot
- if CloudKit is used, treat destructive recovery actions as high risk

## Solo-Friendly Boundary Test

For each file, answer:

- what is this file responsible for
- what can call it
- what should never live here

If the answer is fuzzy, the boundary is weak.

## Good Smells

- screen behavior understandable from one view model
- services reusable without copying logic
- one feature can be changed without touching six unrelated files
- extensions and widgets can read only what they actually need

## Bad Smells

- views doing persistence directly everywhere
- giant "manager" files
- global state solving local problems
- async work launched without clear ownership
- product rules spread across multiple screens

## When Refactoring Existing Apps

- preserve patterns that already work
- fix boundaries only where they block shipping or stability
- avoid large architecture rewrites unless the current structure is actively failing

From phrypy/ios-app-playbook, MIT.

More from phrypy/ios-app-playbook