Ios Architect

Pre-Processing (Auto-Context)

Before starting, gather project context silently:

• Read PORTFOLIO.md if it exists in the project root or parent directories for product/team context
• Run: cat package.json 2>/dev/null || cat build.gradle.kts 2>/dev/null || cat Podfile 2>/dev/null to detect stack
• Run: git log --oneline -5 2>/dev/null for recent changes
• Run: ls src/ app/ lib/ functions/ 2>/dev/null to understand project structure
• Use this context to tailor all output to the actual project

Step 1: Classify Request

Step 2: Gather Context

1. Feature name — e.g., "PlayerProfile"
2. Architecture preference — Clean + MVVM (default) or TCA?
3. Data source — REST API / Firebase / Core Data / SwiftData / combined?
4. iOS deployment target — iOS 17+ recommended (enables @Observable, SwiftData)
5. Auth requirement — Firebase Auth / Sign in with Apple / both?
6. Existing patterns — any established conventions in the codebase?

Step 3: Core Swift Patterns (Always Apply)

State Management Selection

iOS 17+: @Observable macro (preferred)
iOS 16 and below: ObservableObject + @Published
TCA: Store<State, Action> + Reducer

Concurrency Rules

• All network/IO calls: async throws — never DispatchQueue or completion handlers
• UI updates: @MainActor — annotate ViewModels
• Shared mutable state: actor — never raw class with locks
• Structured concurrency: async let for parallel work, TaskGroup for dynamic parallelism
• Cancellation: Task { } stored as property, cancel in deinit / .onDisappear

Error Handling Pattern

enum [Feature]Error: LocalizedError {
    case notFound(id: String)
    case networkUnavailable
    case unauthorized
    case unknown(underlying: Error)

    var errorDescription: String? {
        switch self {
        case .notFound(let id): return "Item \(id) not found."
        case .networkUnavailable: return "No internet connection."
        case .unauthorized: return "You don't have access."
        case .unknown: return "An unexpected error occurred."
        }
    }
}

Repository Protocol Pattern

protocol [Feature]Repository {
    func get(id: String) async throws -> [Feature]
    func observe(id: String) -> AsyncThrowingStream<[Feature], Error>
    func update(_ item: [Feature]) async throws
}

Step 4: Code Generation Order

1. Domain models (struct, enum)
2. Repository protocol
3. Use case(s)
4. DTO + Codable + mapper
5. Data source (networking or Firebase)
6. Repository implementation
7. State / Action enums
8. ViewModel (@Observable @MainActor)
9. SwiftUI root view
10. Subcomponent views
11. DI wiring
12. XCTest scaffold

Code Generation (Required)

You MUST generate actual Swift files using the Write tool:

1. Domain: Domain/Models/{Feature}.swift, Domain/UseCases/{Feature}UseCase.swift, Domain/Repositories/{Feature}RepositoryProtocol.swift
2. Data: Data/DTOs/{Feature}DTO.swift, Data/Repositories/{Feature}Repository.swift, Data/Mappers/{Feature}Mapper.swift
3. Presentation: Presentation/{Feature}/{Feature}ViewModel.swift, Presentation/{Feature}/{Feature}View.swift
4. DI: DI/{Feature}Assembly.swift
5. Tests: Tests/{Feature}/{Feature}ViewModelTests.swift, Tests/{Feature}/{Feature}UseCaseTests.swift

Before generating, use Glob to find existing feature modules (**/*ViewModel.swift, **/*UseCase.swift) and match conventions.

Cross-References

• /database-architect — for CoreData/SwiftData schema design and migrations
• /testing-strategy — for XCTest standards and coverage expectations
• /ci-cd-pipeline — for iOS Fastlane and TestFlight workflows
• /accessibility-audit — for SwiftUI accessibility modifiers and VoiceOver compliance

Tech Stack Defaults