iOS Architecture That Scales: MVVM, DI, and Feature Modules

Quickstart

If you want fast wins, do these in order. They don’t require a full rewrite and they immediately reduce “spooky action at a distance” (where changes in one place break something far away).

Overview

Most architecture debates are really about one thing: where does change go? In a scalable iOS codebase, a new feature should touch a small number of files, live in one place, and be testable without booting half the app.

Feature modules add a fourth dimension: the same layers exist inside each feature, but the feature’s internals stay private. The app shell composes features together at the edges (navigation, deep links, global DI registration).

Core concepts

To make iOS architecture that scales feel concrete, we’ll define the three building blocks (MVVM, DI, modules) and the small “rules of the road” that keep them clean.

MVVM (what it is, and what it isn’t)

In MVVM, the View displays state and forwards user intent, while the ViewModel transforms intent into state changes by calling services. The ViewModel should not know about concrete UI details (no pushing view controllers, no SwiftUI navigation paths, no alert presentation logic beyond “show error state”).

Dependency Injection (DI) as “wiring,” not magic

DI is a simple idea: instead of a type reaching out to find dependencies (singletons, globals), you provide what it needs. The biggest payoff is testability: you can swap a network client for a fake in one line.

Feature modules: structure that enforces boundaries

Feature modules are how you keep a growing app from collapsing into one folder. A feature module typically contains: the screens for a feature, its ViewModels, its feature-local models, and small helpers. The module exposes a minimal public API (often a root view/controller factory), and hides internal details.

Composition root: the one place where wiring is allowed

The composition root is the top of your app where you assemble the object graph: create services, register them, create ViewModels, and build the first screen. For SwiftUI, this is typically your @main App. For UIKit, it can be SceneDelegate or an app coordinator.

Step-by-step

This is a practical, “copy and evolve” path to implement MVVM + DI + feature modules. If you’re migrating a messy app, do it feature-by-feature. If you’re starting fresh, you can do the whole setup in a day.

Step 1 — Decide your feature list and “public API” per feature

Before you create modules, decide what counts as a feature and what it should expose. A good default is: each feature exposes a single entry point (a SwiftUI view or a UIViewController factory), plus lightweight models/events.

Step 2 — Create a module structure (SPM-friendly)

Swift Package Manager (SPM) is the simplest way to modularize modern iOS projects: packages build fast, integrate well, and make dependencies explicit. Start with one feature module and one shared module (only for truly shared code).

# One practical layout (feature-first)
# (You can keep everything in one repo and add packages over time.)

mkdir -p MyApp/Packages
cd MyApp/Packages

# Create a shared module for cross-feature primitives (keep it small)
swift package init --type library --name AppCore

# Create a feature module (repeat per feature)
swift package init --type library --name FeatureProfile

# Suggested tree (conceptual):
# MyApp/
#   App/                 # iOS app target (composition root, navigation shell)
#   Packages/
#     AppCore/           # shared types, networking base, design primitives (only what truly repeats)
#     FeatureProfile/    # screens + VM + feature-specific models
#     FeatureSettings/   # another feature, independent by default

Step 3 — Define service protocols close to where they’re used

Protocols are your seam for DI. A useful default: define a protocol in the feature module that needs it (or in AppCore only if it’s genuinely shared). Concrete implementations can live in AppCore or an Infrastructure package.

Step 4 — Implement MVVM with explicit state (copyable pattern)

This pattern scales because it makes states explicit (loading vs loaded vs error) and makes dependencies injectable. It also works in both SwiftUI and UIKit: SwiftUI binds to @Published, UIKit can observe state changes.

import Foundation
import Combine

// 1) Define a protocol (DI seam)
protocol UserProfileServicing {
  func loadUser(id: UUID) async throws -> User
}

// 2) Keep your domain model simple
struct User: Equatable {
  let id: UUID
  let name: String
}

// 3) ViewModel owns state transitions (not UI navigation)
@MainActor
final class ProfileViewModel: ObservableObject {

  enum State: Equatable {
    case idle
    case loading
    case loaded(User)
    case failed(message: String)
  }

  @Published private(set) var state: State = .idle

  private let service: UserProfileServicing
  private let userID: UUID
  private var loadTask: Task<Void, Never>?

  init(userID: UUID, service: UserProfileServicing) {
    self.userID = userID
    self.service = service
  }

  func onAppear() {
    // Avoid duplicate loads if the view re-appears frequently
    guard case .idle = state else { return }
    refresh()
  }

  func refresh() {
    loadTask?.cancel()
    state = .loading

    loadTask = Task {
      do {
        let user = try await service.loadUser(id: userID)
        state = .loaded(user)
      } catch {
        // Map error to something user-friendly (keep it deterministic for tests)
        state = .failed(message: "Couldn’t load profile. Please try again.")
      }
    }
  }

  func onDisappear() {
    loadTask?.cancel()
    loadTask = nil
  }
}

// Tip for tests:
// Provide a fake service that returns a fixed User (or throws), then assert the state transitions.

Step 5 — Add DI as a convenience (keep it at the edges)

Once you have more than a few services, wiring by hand gets noisy. A small container reduces the boilerplate, but the shape of your dependencies should remain obvious. The pattern below supports overrides (tests, previews, staging) without turning DI into a global mystery.

import Foundation
import SwiftUI

// A tiny DI container (enough for most apps)
final class Container {
  static let shared = Container()

  private var factories: [ObjectIdentifier: () -> Any] = [:]
  private var parent: Container?

  init(parent: Container? = nil) {
    self.parent = parent
  }

  func register<T>(_ type: T.Type, factory: @escaping () -> T) {
    factories[ObjectIdentifier(type)] = factory
  }

  func resolve<T>(_ type: T.Type = T.self) -> T {
    if let factory = factories[ObjectIdentifier(type)], let value = factory() as? T {
      return value
    }
    if let parent {
      return parent.resolve(type)
    }
    fatalError("No registration for \\(type)")
  }

  func makeChild() -> Container {
    Container(parent: self)
  }
}

// SwiftUI Environment hookup (so views can access the container if needed)
private struct ContainerKey: EnvironmentKey {
  static let defaultValue: Container = .shared
}

extension EnvironmentValues {
  var container: Container {
    get { self[ContainerKey.self] }
    set { self[ContainerKey.self] = newValue }
  }
}

// Composition root example (App start)
@main
struct MyApp: App {
  init() {
    let c = Container.shared
    c.register(UserProfileServicing.self) { LiveUserProfileService() }
  }

  var body: some Scene {
    WindowGroup {
      // Resolve at the edge, then inject explicitly into ViewModels
      let c = Container.shared
      ProfileScreen(viewModel: ProfileViewModel(
        userID: UUID(),
        service: c.resolve(UserProfileServicing.self)
      ))
      .environment(\.container, c)
    }
  }
}

// Tests/previews:
// let testContainer = Container.shared.makeChild()
// testContainer.register(UserProfileServicing.self) { FakeUserProfileService() }
// Build the screen using testContainer and you have controlled dependencies.

Step 6 — Keep navigation in the app shell (not in ViewModels)

Navigation is where coupling sneaks back in. A scalable approach is to keep navigation decisions in a coordinator/router (UIKit) or in the app shell / flow container (SwiftUI). ViewModels emit events; the shell interprets them and navigates.

Step 7 — Add tests where they’re cheapest: ViewModels and services

The goal is not “test everything.” The goal is to test the code that breaks most often (logic and IO boundaries) without UI runtime cost. With DI seams, unit tests become tiny and fast.

Step 8 — Scale modules carefully: fewer dependencies, clearer “shared”

Modularization can backfire if you create too many tiny modules or shove everything into shared code. A healthy direction is: features depend on AppCore, but not on each other; the app target depends on all features.

Common mistakes

These pitfalls show up in real iOS apps (not just tutorials). Each one creates coupling, slows iteration, or makes bugs harder to isolate. The fix is usually smaller than you think.

FAQ

Do I need Clean Architecture on top of MVVM?

Not necessarily. If MVVM + DI keeps your ViewModels small and your services well-defined, that’s often enough. Add extra layers (use-cases, interactors) only when you feel real pain: duplicated orchestration logic, complicated business rules, or multiple UIs sharing the same workflows.

Should I use a Coordinator pattern for navigation?

Use a “navigation shell” concept, regardless of framework. In UIKit, coordinators are a proven way to centralize routing. In SwiftUI, you can achieve the same separation by keeping navigation state and routing decisions outside ViewModels (e.g., in an app flow container).

Where should models live: in AppCore or inside features?

Default to feature-local models. Only move models to AppCore when they represent a truly shared concept across multiple features (and you’re confident the definition is stable). Otherwise, keep types close to where they’re used to avoid “global type coupling.”

How do feature modules work with SwiftUI?

Very well—if you expose a small entry point. A feature can export a ProfileScreen (SwiftUI view) or a factory function. The app shell composes features and provides dependencies (via constructor DI or a container resolved at the edge).

Is a DI container required?

No. Constructor injection alone scales surprisingly far. Introduce a container only when wiring becomes repetitive, and keep it limited to the composition root / edges so dependencies remain explicit in core types.

How do I test ViewModels that use async/await?

Inject a fake service and assert state transitions. Keep your ViewModel’s state deterministic and map errors into stable categories. Tests then become: create VM with a fake → call action → await task completion → assert state.

What’s the most important rule for iOS architecture that scales?

Make change local. If a feature change requires touching five unrelated folders, the architecture is leaking. Feature modules + DI seams + MVVM state boundaries work together to keep changes contained.

Cheatsheet

A scan-fast checklist you can keep open while refactoring or starting a new feature.

Wrap-up

Scaling an iOS app is less about picking the perfect pattern and more about enforcing a few boundaries that keep change local. MVVM keeps UI predictable, DI keeps dependencies explicit and testable, and feature modules keep your project from becoming one giant ball of code.

Want to go deeper? The related posts below cover layout rules (SwiftUI), performance profiling, mobile security basics, and deep linking edge cases. Together, they form the “shipping toolbox” around a scalable architecture.

Related posts

• SwiftUI Layout: The Rules That Stop the ‘Why Is It Doing That?’
• Make iOS Apps Smooth: Instruments Profiling Starter Guide
• Mobile App Security Basics: Storage, TLS, and Jailbreak Signals
• Deep Links That Work: Universal Links, App Links, and Edge Cases
• Jetpack Compose: State, Effects, and UI That Doesn’t Jitter
• Android Studio Profilers: Fix the 90% of Slowdowns