Swift Modular Architecture: The Complete Guide

Published on · Updated · 31 min

Wlad
Wlad
Founder & Swift Tech Lead
Swift Architecture SPM Modularization Clean Architecture iOS

Modularizing a Swift project transforms a hard-to-maintain monolith into an ecosystem of autonomous, testable, and reusable modules. This guide covers fundamentals, advanced patterns, Swift 6.2 integration, and best practices for building iOS, macOS, visionOS, and server applications at industrial scale.

Why Modularize?

A monolithic Swift project works well at first. But as it grows, problems accumulate: exponential compilation times, constant merge conflicts, testing difficulties, invisible coupling between components.

Symptoms of a Suffering Monolith

SymptomImpactCritical Threshold

Build time > 5 min

Degraded productivity

10 min

Frequent merge conflicts

Team friction

3/week

Slow or unstable tests

Inefficient CI/CD

15 min

Difficult onboarding

Learning curve

2 weeks

Everything breaks when touching X

Hidden coupling

Critical

Concrete Benefits of Modularization

Modularization brings measurable gains:

  • Incremental compilation: only modified modules are recompiled

  • Build parallelization: independent modules compile in parallel

  • Test isolation: each module has its own unit tests

  • Clear ownership: one team = one or more modules

  • Reusability: Core modules are shared across apps

  • Explicit boundaries: dependencies are declared, not implicit

Swift Package Manager Fundamentals

Swift Package Manager (SPM) has been the standard tool for modularization since Swift 5.3. It offers native Xcode integration and supports all Apple platforms.

Anatomy of a Package.swift

Products: Library vs Executable

TypeUsageWhen to Use

.library (static)

Linked to final binary

Default, best performance

.library (dynamic)

Loaded at runtime

Shared between multiple targets

.executable

Standalone binary

CLI, scripts, server

.plugin

Xcode/SPM extension

Build tools, linters

Targets and Dependencies

A target is a compilation unit. Dependencies between targets define the build graph:

Modularization Patterns

Pattern 1: Feature Modules

Each business feature is an autonomous module containing UI, logic, and tests:

Public entry point implementation:

Pattern 2: Core Modules (Infrastructure)

Core modules provide shared foundations:

NetworkKit example with Swift Concurrency:

Pattern 3: Domain Modules (Clean Architecture)

For complex projects, separate business domain from implementation details:

Implementation with dependency inversion:

Modular Project Structure

Monorepo with Local Packages

Recommended structure for a modular iOS/macOS project:

Root Package.swift (Umbrella)

Modular Dependency Injection

Pattern: Dependency Container

Pattern: Protocol Witness with @Dependencies

For a more testable approach with Point-Free's swift-dependencies:

Swift 6.2 and Modularization

Strict Concurrency per Module

Swift 6.2 allows configuring concurrency level per target:

MainActor by Default (defaultIsolation)

With Swift 6.2, new UI modules can opt into MainActor by default:

Sendable Boundaries Between Modules

Boundaries between modules must respect Sendable:

Build Optimization

Maximum Parallelization

SPM compiles independent modules in parallel. To maximize parallelism:

    • Minimize dependencies: each dependency adds a sequencing constraint
    • Extract "leaf" modules: modules with no internal dependencies
    • Avoid cycles: a cycle forces sequential compilation

Conditional Build with Feature Flags

Build Metrics

Script to measure compilation times per module:

Modular Testing

Test Structure per Module

Shared TestSupport Module

Tests with Injected Dependencies

Modular CI/CD

Optimized GitHub Actions

Migrating from a Monolith

Strangler Fig Strategy

Migrate progressively without big-bang:

    • Identify boundaries: map existing dependencies
    • Extract CoreKit: start with utilities without dependencies
    • Create protocols: define interfaces before extracting
    • Extract module by module: one feature at a time
    • Clean up: remove duplicated code

Pitfalls and Anti-Patterns

1. Over-Modularization

Creating too many modules adds complexity without benefit:

Rule: If a module has fewer than 5 files or < 500 lines, it should probably be merged.

2. Circular Dependencies

3. Leaky Abstractions

4. God Module

5. Transitive Public Import

Modularization Checklist

Before creating a new module:

  • The module has a clear and unique responsibility

  • The module has at least 5 files / 500 lines of code

  • Dependencies are explicit and minimal

  • No circular dependency

  • Public API is documented

  • A test target exists

  • The module is Sendable-safe (Swift 6)

Before merging a PR affecting modules:

  • The dependency graph remains acyclic

  • Build times haven't increased significantly

  • All tests pass

  • Documentation is up to date

Going Further

A well-designed modular architecture is an investment that pays off in the long run. It enables teams to work in parallel, reduces build times, and makes code more maintainable.

Official Resources