Taming iOS Architecture Decay: Strategies to Boost Build Efficiency

Background

In recent years the complexity of the iOS codebase at Alibaba.com has caused severe build slowdowns and frequent packaging failures, dramatically reducing development efficiency. Since 2016 the client has evolved from a simple modular architecture to a massive monolithic project with over 100 self‑maintained modules, many of which suffer from circular and reverse dependencies, non‑conforming LLVM module specifications, and outdated CocoaPods versions.

Problems Identified

1. High Module Packaging Complexity

Modules are inter‑mixed, with missing spec files and inconsistent header imports. Compatibility scripts were added to force compilation, which prevented proper spec maintenance and led to chaotic header references.

2. Incompatible Environments & Build Failures

Outdated CocoaPods (1.2/1.5) cannot be upgraded due to legacy code, while newer syntax in the main project requires CocoaPods 1.9+, causing frequent build failures.

3. Wasted Development Resources

Each failed module build consumes roughly two hours of developer time; over 200 failures per quarter translate to about 90 person‑days lost annually.

4. Swift Integration Difficulties

Strict LLVM module rules reject circular dependencies and improper header imports, making Swift adoption painful and error‑prone.

5. Historical Code Cleanup Challenges

Legacy modules remain tightly coupled, preventing removal of obsolete code and inflating binary size.

Solution Overview

Data‑Driven Diagnosis

Collected module build failure statistics and interview feedback to quantify the impact of architectural decay.

Global Dependency Mapping

Developed a tool that scans source files, extracts import statements, maps them to their originating frameworks, and generates a complete dependency graph using the DOT language.

Layered & Inverted Governance

Classified modules into four quadrants based on dependency depth and presence of cycles, then tackled governance from the lowest layer upward, eliminating cycles and enforcing LLVM compliance before moving to higher‑level business modules.

Automation

Built an architecture management engine that automatically:

Analyzes and repairs missing spec dependencies.

Generates umbrella headers.

Normalizes header imports.

This automation covers about 95% of required code changes, leaving developers to handle only high‑level API and routing adjustments.

require 'cocoapods'
require 'cocoapods-core'
require 'xcodeproj'

def DependencesAnalyser.main(contextHelper, projectToolPath, moduleName, allModuleNames)
  iOSProjectDir = contextHelper.projectDir
  podDir = contextHelper.podDir
  iOSProjectName = contextHelper.projectName
  sourceDir = contextHelper.sourceDir
  return nil if sourceDir.nil?
  allheadPaths = getSourceHeaderPath(sourceDir)
  importHeaders = parseHeaderNameFromQuotationImport(allheadPaths)
  dependences = parseFrameworkNameFromAngleBracketsImport(allheadPaths)
  dependencesFromQuatationImport = findFrameNameFromQuatationImport(podDir, importHeaders)
  dependences += dependencesFromQuatationImport
  filtedDependences = filterDepencences(dependences, projectToolPath, moduleName, allModuleNames)
  modify_spec_file(filtedDependences, contextHelper)
  filtedDependences
end

Long‑Term Safeguards

Implemented continuous integration gates that enforce module compliance, upgraded the main project to CocoaPods 1.9.1 with cycle detection, and standardized build scripts to generate module projects dynamically, eliminating divergent build configurations.

Conclusion

Architectural decay behaves like a hidden virus, eroding productivity and increasing risk. By systematically analyzing dependencies, applying layered refactoring, and automating repetitive fixes, teams can restore a clean, maintainable iOS codebase and establish processes that prevent future decay.