Componentization Architecture for Large-Scale Mobile Apps: Principles, Challenges, and Best Practices

Introduction – Componentization is a common architectural approach for medium and large mobile apps. The author shares personal experience, motivations, and the problems addressed by moving from a monolithic single‑repo to a multi‑repo component model.

Why componentization is needed – Multiple co‑existing apps, growing feature sets, and diverse technology stacks (different languages, cross‑platform UI frameworks) strain monolithic builds, causing slow compilation, merge conflicts, and difficulty in code ownership.

Key challenges

Balancing component granularity: too coarse leads to tight coupling, too fine increases repository overhead and dependency lookup cost.

Defining component responsibilities and boundaries.

Managing dependencies (direct strong coupling vs. indirect loose coupling).

Cross‑technology communication (URL schemes, notifications, service interfaces, event queues).

Ensuring version compatibility and avoiding break‑changes.

Component splitting principles – Use a layered architecture: Foundation (base), Business Common (routing, UI, services), Business Implementation (native pages, cross‑platform containers), and App Host. Identify whether a component is basic or business, and decide if it should be exposed directly or via an interface.

Dependency management – Prefer loose‑coupled communication for business components, enforce rules such as no reverse dependencies, third‑party libraries must not depend on other components, and base components must not depend on business components.

Service interface design – Combine Objective‑C protocols for compatibility with Swift extensions. Example implementation:

// @objc protocol
@objc public protocol JDCartService {
    func addCart(request: JDAddCartRequest, onSuccess: () -> Void, onFail: () -> ())
}
// Swift protocol
public protocol CartService: JDCartService {
    func addCart() async
    func addCart(onCompletion: Result)
}
// Implementation
class CartServiceImp: NSObject, CartService {
    // implements both ObjC and Swift protocols
}

Versioning and compatibility – Keep APIs backward compatible, add new APIs instead of modifying existing ones, encapsulate parameters in objects, avoid changing constants/enums, and limit major version releases.

Quality assurance – Integrate CI checks for dependency violations, enforce component‑level rules, and perform runtime checks for missing service implementations, illegal ObjC runtime calls, and unused components. Track metrics such as number of base component dependencies, business service dependencies, and erroneous dependency counts.

Practical considerations – Componentization introduces overhead (multiple git repos, build time, debugging challenges) and requires tooling for version management and CI. Small projects can still benefit by starting with coarse components and evolving toward finer granularity, possibly using a monorepo with folder‑level isolation.

Conclusion – No perfect architecture exists; teams must continuously monitor and refactor component boundaries, adapt to organizational changes, and balance the benefits of modularity against the added complexity and maintenance cost.