ios-architecture

name	ios-architecture
description	Use when defining iOS module boundaries, dependency direction, state ownership, App Intent integration, or AI provider seams; use ios-development for feature implementation details.
metadata	{"portable":true,"compatible_with":["claude-code","codex"]}

iOS Architecture

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Designing, reviewing, or refactoring iOS app architecture, modular boundaries, dependency injection, navigation, production patterns, or large-team delivery.
• The task mentions MVVM, clean architecture, Swift patterns, UIKit/SwiftUI boundaries, modularization, App Intents, Siri/Spotlight, Foundation Models, Core AI, provider abstraction, scaling, CI impact, or maintainability.
• A narrow retired iOS architecture skill is referenced by name.

Do Not Use When

• The request is only about general iOS implementation; use ios-development.
• The request is only about UI polish; use ios-ui-ux-design.
• The request is only about persistence, platform capabilities, quality/release, or security/RBAC; use those parent skills.

Required Inputs

• App scope, platform targets, current module layout, UI framework mix, backend/API shape, team size, release constraints, and the concrete architectural decision or defect.
• Existing project files or diagrams when implementation or review is requested.

Workflow

1. Load ios-development first for shared iOS implementation standards.
2. Identify the architecture concern: app composition, module boundaries, Swift patterns, scale practices, or production gotchas.
3. Load only the matching reference below.
4. Produce a concrete architecture decision, refactor plan, review finding, or implementation patch with tests and rollout notes when relevant.

Quality Standards

• Architecture decisions must preserve platform-native UX, testability, dependency clarity, and predictable release behaviour.
• Module boundaries must have explicit ownership, public APIs, dependency direction, and migration steps.
• Any scale guidance must include CI, build-time, ownership, or observability impact when it changes delivery workflow.

Anti-Patterns

• Creating abstract layers without a current complexity or testability problem.
• Mixing UIKit, SwiftUI, model state, and networking without clear ownership.
• Treating large-team practices as default for small apps.

Outputs

• iOS architecture decision record, module map, refactor plan, review findings, or implementation guidance.

Inputs

Artefact	Produced by	Required?	Why
Product flows and quality attributes	Product discovery	required	Establishes architectural drivers
API and error contract	api-design-first	conditional	Defines client boundaries
Threat model	ios-security-and-rbac	required for protected data	Constrains trust boundaries

Decision Rules

Condition	Choice
Small feature with one owner	Feature module, not a new framework layer
Reused domain behaviour with stable semantics	Extract a dependency-inverted package
Framework or vendor API may change	Hide it behind a narrow protocol
Cross-feature mutable state	Assign one owner and expose immutable observations

Degraded Mode

Without repository access, return assumptions and an architecture sketch only. Without builds, mark dependency cycles, actor isolation, package visibility, and launch behaviour as unverified. If execution is unavailable, keep build-dependent findings in the exception register.

Domain Anti-Patterns

• Creating modules by screen count. Fix: split on ownership and dependency boundaries.

• Putting SwiftUI types in the domain layer. Fix: map presentation state at the feature edge.

• Using a global service locator. Fix: inject explicit protocols at composition roots.

• Sharing mutable state across actors. Fix: assign actor ownership and send values.

• Abstracting a single stable implementation prematurely. Fix: add a seam only for a named change risk.

• references/ios-architecture-advanced.md for dependency injection, MVVM variants, navigation, and testable architecture patterns.

• references/ios-at-scale.md for modularization, large-team workflows, build systems, and CI practices.

• references/ios-production-patterns.md for production UIKit/SwiftUI lifecycle and app-store-proven implementation rules.

• references/ios-swift-design-patterns.md for Swift-idiomatic patterns and reusable implementation recipes.

• references/app-intelligence-architecture-wwdc26.md for App Intents, semantic indexing, Foundation Models/Core AI provider boundaries, evaluation layers, and agent-safe module ownership.

Read next

• ios-development for implementation; ios-quality-and-release for verification and distribution.