Transforming Huolala iOS: Componentized Architecture & Efficient Pod Management

Background

During the growth of the Huolala freight iOS client, increasing team size and business complexity led to tangled code dependencies, poor maintainability, and inefficient parallel development across multiple business lines. Three major pain points were identified: pod version management issues, an inadequate component routing solution, and multi‑repo code submission difficulties.

Related Research

Current Architecture Overview

The existing architecture suffered from heavy coupling between business modules and shared utilities, with business logic intermingled in common modules and vice‑versa.

iOS Industry Architecture Goals

Component‑based architecture

Separation of interfaces and services

Single‑repo with multiple components

Componentization Principles

Abstraction : Extract common patterns from specific problems and create reusable, stable low‑level modules.

Stable Dependency : Stable components must not depend on frequently changing ones.

True Decoupling : Components should be isolated beyond mere file‑folder separation, avoiding circular header imports.

Guidelines

Separate public and foundational libraries into independent pods.

Encapsulate third‑party libraries behind an adapter layer.

Gradually split business modules into distinct pods, ensuring appropriate granularity.

Manage private pods via a centralized PodDepeLock repository.

Solution Design and Formulation

Goal Decomposition

Improve development, build, and testing efficiency.

Enhance framework stability and extensibility, reducing production incidents.

Address the three identified problems.

Pod Dependency Management

Create a dedicated pod PodDepeLock to lock versions of major component libraries, have each component’s Podfile reference this lock, and centralize all third‑party version handling.

Component Routing Design

Introduce SHSpringRouter based on a protocol‑class pattern, providing a core routing middle‑layer, safety service base class, and runtime logging/reporting.

Architecture Layering

Shell layer: stable entry point for the app.

Business line layer: separate teams for moving, city‑wide, and map services.

Interface middle‑layer: centralized protocol‑based APIs.

Service layer: concrete implementations of protocols, either as independent pods or sub‑pods.

Base layer: foundational utilities and third‑party libraries.

Multi‑Component Single‑Repo Strategy

Business modules are elevated to their own repositories (e.g., SHUser), while shared tools reside in a common module repository ( CommonModule), enabling independent compilation and deployment.

Conclusion

Project Outcomes

Reduced pod version conflicts, eliminating frequent install failures.

Improved routing runtime efficiency by ~50% (0.846 ms → 0.418 ms per 50 calls on iPhone 6 in Debug mode).

Accelerated component integration: API calls now use protocol‑based macros, cutting integration time to ~10 seconds.

Streamlined business code submission by isolating business repositories.

No production incidents reported across five iterations and fifteen feature branches.

Lessons Learned

Initial planning and pre‑research phases were longer than ideal.

Further granularity in component splitting is needed.

Current routing does not fully support model‑based parameter passing.

Common module misuse remains a risk.

References

iOS Componentization Solutions

iOS Architecture Discussions

Alibaba BeeHive Framework Analysis

iOS Modular Architecture Practices

Uber Rider App Architecture Engineering