Get the FREE Ultimate OpenClaw Setup Guide →

swift-architecture-audit

Scanned
npx machina-cli add skill jeremieb/swift-unit-test-instructions/swift-architecture-audit --openclaw
Files (1)
SKILL.md
5.8 KB

Swift Architecture Audit

Instructions

Step 1: Explore the Project Structure

Identify the UI framework in use (SwiftUI, UIKit, or Mixed) by scanning the project — look for @main, UIApplicationDelegate, or UIHostingController. Then load the matching structure reference from ../swift-project-setup/references/ and use it as the baseline when identifying structural deviations.

Use subagents to parallelize exploration of large codebases.

Scan for:

  • All feature folders and their naming patterns
  • Number of UIViewController subclasses vs ViewModel types
  • Number of SwiftUI View types
  • Presence of protocol files in Core/ or Protocols/
  • Existing test targets and approximate test count

Step 2: MVVM Compliance Check

Read representative files from 3-5 key features. Look for:

Red flags (report each with file:line):

  • Business logic, network calls, or storage access directly inside SwiftUI View bodies
  • Business logic inside UIViewController subclasses
  • URLSession.shared or UserDefaults.standard called from Views or ViewControllers
  • Missing ViewModel for any screen with non-trivial state
  • @State or @StateObject holding data that belongs in a ViewModel or service

Green flags (note these):

  • ObservableObject or @Observable ViewModels with clear state
  • Services and repositories injected via initializer or @Environment
  • Thin View layer (only layout and presentation)
  • Coordinator / navigation layer separate from ViewModels

Step 3: Testability Assessment

For each audited type, check:

  • Are dependencies hardcoded (let service = NetworkService()) instead of injected?
  • Do networking/storage types hide behind protocols?
  • Are global singletons used without injection support?
  • Is there any existing test coverage? How much?
  • Are ViewModels testable in isolation (no UIKit/SwiftUI imports)?

Scoring:

  • High testability: Protocols + DI everywhere, existing tests
  • Medium testability: Some DI, some singletons, few tests
  • Low testability: No protocols, no DI, no tests — refactoring needed before testing is possible

Step 4: Concurrency Review

Identify:

  • Completion handler usage where async/await should be used (new code)
  • DispatchQueue.main.async scattered in ViewModel or service layers (use @MainActor)
  • @Published properties updated from background threads without actor isolation
  • Non-Sendable types crossing actor boundaries (potential data races)
  • sleep() anywhere in the codebase

Step 5: Anti-Pattern Inventory

Anti-PatternImpactAction
Massive ViewControllerUntestable, unmaintainableExtract ViewModel + Services
No protocol for external depsCan't mock in testsWrap in protocol
Singleton abuseHidden couplingInject via init
Completion handlers in new codeFragile asyncMigrate to async/await
Force unwrap in productionCrashesReplace with guard/if let
Business logic in ViewUntestableMove to ViewModel

Step 6: Generate Audit Report

# Architecture Audit: [ProjectName]
Date: [date]

## Health Summary
Overall: [Good / Needs Work / Critical Issues]
MVVM Compliance: [High / Medium / Low]
Testability: [High / Medium / Low]
Concurrency: [Modern / Mixed / Legacy]

## Critical Issues (Fix First)
- [issue] in `FileName.swift:line` — [impact and suggested fix]

## Architectural Violations
- [violation] — [file(s) affected] — [recommended refactoring]

## Testability Blockers
- [blocker] — [which types are affected] — [fix: add protocol / inject dependency]

## Concurrency Issues
- [issue] — [file:line] — [suggested migration]

## Refactoring Priority
1. [Most critical — blocks testing or causes crashes]
2. [High priority — causes maintainability issues]
3. [Medium priority — worth cleaning up]
4. [Low priority / nice to have]

## Strengths
- [what the codebase does well — acknowledge good patterns]

Examples

Example 1: Legacy UIKit project

User says: "Audit the architecture, I want to add tests but everything is hard to test"

Actions:

  1. Explore folder structure with subagent
  2. Read 3 ViewControllers — assess logic placement
  3. Check for protocol/DI usage across service layer
  4. Generate prioritized audit report with specific files and lines

Example 2: SwiftUI project onboarding

User says: "I just joined this project, give me an architecture overview"

Actions:

  1. Map all feature modules
  2. Identify patterns: which architecture style is in use (MVVM, MV, etc.)
  3. Note testing state
  4. Generate onboarding summary + list of known issues

References

  • ../swift-project-setup/references/structure-swiftui.md — expected SwiftUI layout
  • ../swift-project-setup/references/structure-uikit.md — expected UIKit layout
  • ../swift-project-setup/references/structure-mixed.md — expected Mixed layout
  • ../swift-project-setup/references/file-naming.md — naming rules and "What Never Goes Where" table

Troubleshooting

Codebase is too large to read fully: Use subagents to parallelize exploration. Focus the audit on the 3-5 most critical or highest-risk features (main flows, payment, authentication). Note coverage limitations in the report.

No clear architecture pattern found: Document what exists honestly. Don't assume intent. Recommend a migration path to MVVM with concrete first steps.

Source

git clone https://github.com/jeremieb/swift-unit-test-instructions/blob/main/skills/swift-architecture-audit/SKILL.mdView on GitHub

Overview

Swift Architecture Audit analyzes a SwiftUI/UIKit codebase to evaluate MVVM compliance, testability, concurrency patterns, and anti-patterns. It helps onboard new contributors, pinpoint architectural issues, and plan refactors to improve maintainability and testability.

How This Skill Works

The process scans project structure to identify UI framework, checks MVVM compliance across 3-5 key features, evaluates testability and concurrency concerns, inventories anti-patterns, and then generates a structured audit report with prioritized fixes.

When to Use It

  • When you want to audit the codebase to surface architectural and testing issues
  • When you need to review the architecture for maintainability and scalability
  • When onboarding to this project to understand structure and risks
  • When analyzing the code structure for MVVM compliance and separation of concerns
  • When you need to find issues in the code and determine what needs refactoring

Quick Start

  1. Step 1: Explore the project structure to determine UI framework and references
  2. Step 2: Run MVVM compliance, testability, concurrency, and anti-pattern checks across 3-5 key features
  3. Step 3: Generate an audit report with health summary, critical issues, and actionable fixes

Best Practices

  • Inject dependencies via initializer or environment to enable mocking
  • Keep business logic out of Views and ViewControllers; move to ViewModels or services
  • Use ObservableObject/@Published ViewModels with a thin View layer for presentation
  • Separate navigation/coordination from ViewModels and use protocols for external deps
  • Avoid globals/singletons; migrate to async/await and proper concurrency with @MainActor when updating UI

Example Use Cases

  • Onboard a new engineer to a SwiftUI project and quickly surface wiring and testing gaps
  • Review a legacy UIKit app to identify where MVVM refactors are needed
  • Diagnose screens that are hard to test due to business logic in views or controllers
  • Identify and replace singletons and non-mockable dependencies with protocol-based abstractions
  • Plan a refactor to improve testability and concurrency safety across features

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers