SwiftUI Architecture Review Skill

This skill provides comprehensive architectural analysis for SwiftUI iOS applications, focusing on MVVM patterns, state management, view complexity, and overall code quality.

When to Use This Skill

Use this skill when:

• Reviewing SwiftUI code architecture
• Refactoring existing SwiftUI applications
• Establishing architecture standards for a project
• Conducting pre-release architecture audits
• Training developers on SwiftUI best practices
• Identifying technical debt
• Optimizing app performance and maintainability

Quick Start

Basic Architecture Review

For a comprehensive architecture analysis of a SwiftUI project:

python scripts/analyze_architecture.py /path/to/ios/project

This generates:

• Architecture quality score (0-100)
• Categorized issues (critical, warning, info)
• Detailed findings by category
• JSON report for CI/CD integration

Generate Refactoring Recommendations

To get specific, actionable refactoring advice with code examples:

python scripts/generate_refactoring_recommendations.py /path/to/ios/project

This produces:

• Prioritized refactoring opportunities
• Before/after code examples
• Benefits of each refactoring
• Markdown and JSON reports

Core Analysis Categories

1. MVVM Implementation Quality

What it checks:

• ViewModel conformance to ObservableObject or @Observable
• Separation of concerns (no SwiftUI imports in ViewModels)
• Business logic location (ViewModel vs View)
• View-specific logic in ViewModels (colors, fonts, layout)
• Direct model manipulation from Views
• Multiple ViewModels per View

Reference: See references/mvvm-patterns.md for detailed patterns and examples

Key indicators:

• ✅ ViewModels are UI-framework agnostic
• ✅ Business logic resides in ViewModels
• ✅ Views focus only on presentation
• ❌ ViewModels import SwiftUI
• ❌ Complex calculations in View body
• ❌ Direct model mutations from Views

2. State Management Patterns

What it checks:

• Appropriate use of @State, @StateObject, @ObservedObject, @EnvironmentObject, @Binding
• @State with reference types (should be @StateObject)
• Excessive @State properties (>5 suggests need for ViewModel)
• Missing @Published properties in ObservableObject
• Redundant/derived state
• State encapsulation (private vs public)
• ObservableObject without @Published properties

Reference: See references/state-management.md for decision trees and patterns

Key indicators:

• ✅ @State for view-local value types
• ✅ @StateObject for owned ViewModels
• ✅ @ObservedObject for passed ViewModels
• ✅ @EnvironmentObject for app-wide services
• ❌ @State with reference types
• ❌ 5+ @State properties in one view
• ❌ Public @State properties

3. View Decomposition

What it checks:

• View size (lines of code)
• View nesting depth (>4 levels)
• Repeated UI patterns
• Logical section boundaries
• View responsibilities

Reference: See references/view-decomposition.md for decomposition strategies

Size thresholds:

• >500 lines: Critical - definitely needs decomposition
• >300 lines: Warning - consider decomposition
• >200 lines: Info - review for logical boundaries
• <100 lines: Usually fine

Nesting thresholds:

• >4 levels: Consider extracting subviews
• >6 levels: Definitely extract subviews

4. Separation of Concerns

What it checks:

• Multiple ViewModel dependencies
• Networking code in Views
• Database operations in Views
• File I/O in Views
• Heavy computation in Views

Key indicators:

• ✅ Views delegate to ViewModels
• ✅ Services handle networking/persistence
• ✅ ViewModels coordinate business logic
• ❌ Views with URLSession calls
• ❌ Views with 3+ ViewModel dependencies
• ❌ Views accessing Core Data directly

5. Navigation Architecture

What it checks:

• NavigationStack usage
• Navigation anti-patterns (NavigationLink in Button)
• Nested NavigationStacks
• Modal presentation patterns
• Deep linking support

Reference: See references/navigation-patterns.md for coordinator patterns

Key indicators:

• ✅ Single NavigationStack per tab
• ✅ Value-based navigation
• ✅ Coordinator pattern for complex flows
• ❌ NavigationLink wrapped in Button
• ❌ Multiple nested NavigationStacks
• ❌ Hardcoded navigation destinations

6. Performance Optimization

What it checks:

• Expensive computations in view body
• Over-observation of state
• List performance issues
• Image loading patterns
• Background processing
• Memory leaks and retain cycles

Reference: See references/performance-optimization.md for optimization patterns

Key indicators:

• ✅ List/LazyVStack for large collections
• ✅ AsyncImage for remote images
• ✅ Background threads for heavy work
• ✅ [weak self] in closures
• ❌ Complex calculations in body
• ❌ ScrollView + ForEach for large lists
• ❌ Heavy processing on main thread

Workflow

Step 1: Run Automated Analysis

Start with the automated architecture analyzer:

cd /path/to/ios/project
python /path/to/skill/scripts/analyze_architecture.py .

Review the output:

• Architecture Score: Overall quality (0-100)
• Critical Issues: Must fix before release
• Warnings: Should fix for better quality
• Info: Consider for improvement

Step 2: Review Findings by Category

The analysis groups issues into categories:

1. MVVM violations
2. State management issues
3. View size/complexity issues
4. Separation of concerns violations
5. Navigation anti-patterns

For each issue, review the file and line number provided.

Step 3: Generate Refactoring Recommendations

Get specific, actionable advice:

python /path/to/skill/scripts/generate_refactoring_recommendations.py .

This provides:

• Prioritized recommendations (high/medium/low)
• Before/after code examples
• Benefits of each refactoring
• Implementation guidance

Step 4: Deep Dive with References

For detailed understanding of patterns, consult the reference guides:

MVVM Patterns:

view references/mvvm-patterns.md

Learn about:

• Core MVVM principles
• Common anti-patterns
• Quality indicators
• Refactoring patterns

State Management:

view references/state-management.md

Learn about:

• Property wrapper decision trees
• State management patterns
• Anti-pattern detection
• Common refactorings

View Decomposition:

view references/view-decomposition.md

Learn about:

• When to decompose views
• Decomposition strategies
• View hierarchy best practices
• Performance considerations

Navigation Architecture:

view references/navigation-patterns.md

Learn about:

• NavigationStack patterns
• Coordinator pattern
• Modal presentation
• Deep linking

Performance Optimization:

view references/performance-optimization.md

Learn about:

• View update optimization
• List performance
• Image handling
• Background processing
• Memory management

Step 5: Apply Refactorings

Work through recommendations by priority:

1. High priority first:

   • Large views (>500 lines)
   • Critical MVVM violations
   • Performance blockers
   • Navigation anti-patterns

2. Medium priority next:

   • State management improvements
   • Coordinator pattern adoption
   • Separation of concerns fixes

3. Low priority later:

   • Modernization (@Observable)
   • Code style improvements
   • Minor optimizations

Step 6: Re-analyze

After applying refactorings, run the analysis again:

python scripts/analyze_architecture.py .

Track improvement:

• Architecture score should increase
• Issue count should decrease
• Code quality improves

Integration with Development Workflow

CI/CD Integration

Add architecture checks to your CI pipeline:

# .github/workflows/architecture-review.yml
name: Architecture Review
on: [pull_request]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Architecture Analysis
        run: python scripts/analyze_architecture.py .
      - name: Check Score Threshold
        run: |
          SCORE=$(cat architecture_report.json | jq '.summary.architecture_score')
          if [ $SCORE -lt 70 ]; then
            echo "Architecture score $SCORE is below threshold of 70"
            exit 1
          fi

Pre-commit Hook

Add architecture checks to pre-commit:

#!/bin/bash
# .git/hooks/pre-commit

python scripts/analyze_architecture.py .
SCORE=$(cat architecture_report.json | jq '.summary.critical')

if [ $SCORE -gt 0 ]; then
  echo "❌ Critical architecture issues found!"
  exit 1
fi

Code Review Checklist

Use this checklist during code reviews:

MVVM:

• ViewModels are UI-framework agnostic
• Business logic in ViewModels, not Views
• No view-specific logic in ViewModels

State Management:

• Appropriate property wrappers used
• No excessive @State properties (>5)
• @Published used in ObservableObject

View Structure:

• Views under 300 lines
• Nesting depth under 4 levels
• Clear separation of concerns

Navigation:

• Value-based navigation used
• No navigation anti-patterns
• Single NavigationStack per tab

Performance:

• Lists use LazyVStack or List
• Heavy work on background threads
• No retain cycles

Architecture Quality Scoring

The analyzer assigns a score (0-100) based on:

Deductions:

• Critical issue: -15 points
• Warning: -5 points
• Info: -1 point

Score ranges:

• 90-100: Excellent - production-ready architecture
• 70-89: Good - minor improvements needed
• 50-69: Needs Improvement - refactoring recommended
• 0-49: Poor - significant refactoring required

Target scores:

• Minimum for production: 70
• Target for new projects: 85+
• Excellence goal: 90+

Common Refactoring Patterns

Pattern 1: Consolidate @State into ViewModel

Before:

struct FormView: View {
    @State private var name = ""
    @State private var email = ""
    @State private var phone = ""
    @State private var isSubmitting = false
}

After:

struct FormView: View {
    @StateObject private var viewModel = FormViewModel()
}

class FormViewModel: ObservableObject {
    @Published var name = ""
    @Published var email = ""
    @Published var phone = ""
    @Published var isSubmitting = false
}

Pattern 2: Extract Large View into Sections

Before:

struct DashboardView: View {
    var body: some View {
        ScrollView {
            VStack {
                // 500+ lines of mixed content
            }
        }
    }
}

After:

struct DashboardView: View {
    var body: some View {
        ScrollView {
            VStack {
                HeaderSection()
                StatsSection()
                ActivitySection()
                FooterSection()
            }
        }
    }
}

Pattern 3: Use Coordinator for Multiple ViewModels

Before:

struct ComplexView: View {
    @StateObject var userVM = UserViewModel()
    @StateObject var statsVM = StatsViewModel()
    @StateObject var settingsVM = SettingsViewModel()
}

After:

struct ComplexView: View {
    @StateObject var coordinator = ViewCoordinator()
}

@Observable
class ViewCoordinator {
    var user: User
    var stats: Stats
    var settings: Settings
}

Pattern 4: Value-Based Navigation

Before:

NavigationLink {
    DetailView(item: item)
} label: {
    Text(item.name)
}

After:

NavigationLink(value: item) {
    Text(item.name)
}
// At root level:
.navigationDestination(for: Item.self) { item in
    DetailView(item: item)
}

Tips for Best Results

1. Run analysis early and often - Catch issues before they compound
2. Start with critical issues - Fix high-priority items first
3. Use reference guides - Deep dive into patterns as needed
4. Measure improvement - Track architecture score over time
5. Integrate into workflow - Make architecture review part of development
6. Team alignment - Share findings and standards with team
7. Incremental improvement - Don't try to fix everything at once

Limitations

This skill cannot:

• Analyze Objective-C code (Swift only)
• Detect all runtime issues
• Guarantee crash-free code
• Replace human architectural judgment
• Analyze proprietary frameworks

For comprehensive app quality, combine with:

• Unit and UI testing
• Manual code review
• Runtime profiling with Instruments
• App Store submission review skill

Output Files

The scripts generate these files:

architecture_report.json

• Complete analysis results
• Structured for CI/CD integration
• All issues with metadata

refactoring_recommendations.md

• Human-readable recommendations
• Before/after code examples
• Prioritized action items

refactoring_recommendations.json

• Structured recommendation data
• For tooling integration

Additional Resources

All reference guides are available in the references/ directory:

• mvvm-patterns.md - MVVM implementation patterns
• state-management.md - State management decision trees
• view-decomposition.md - View extraction strategies
• navigation-patterns.md - Navigation architecture
• performance-optimization.md - Performance best practices

Read these for detailed examples, anti-patterns, and refactoring strategies.

Summary

This skill provides: ✅ Automated architecture analysis
✅ Quality scoring (0-100)
✅ Specific refactoring recommendations
✅ Before/after code examples
✅ Comprehensive reference guides
✅ CI/CD integration support
✅ Performance optimization guidance

Use this skill to maintain high-quality SwiftUI architecture, reduce technical debt, and build maintainable iOS applications.