SPM Modular Programming Architecture

FraserScottMorrison — Mon, 13 Jul 2026 07:43:00 +0000

Let me frame this article with a couple of not-so-bold predictions for software development.
First, agentic coding will be responsible for the majority of code written. This is already achievable today with an optimised development harness and spec-driven development.

As a consequence, I expect feature development to accelerate dramatically resulting in codebases that continue to grow in both size and complexity. This is a particular concern for enterprise applications, which are already operating at significant scale.

To prepare for this new era of code growth, architecture must prioritise modularity, isolation, and clear dependency boundaries.

This iOS architecture demonstrates a scalable approach that uses Swift Package Manager (SPM) as the foundation for modular application design.

Core Concept

At the heart of this architecture is a simple idea:

The Xcode project should be almost empty — everything lives in Swift Packages.

Key principles:

The Xcode project is intentionally extremely thin; ideally only 10-15 lines of code
All features, shared logic, and UI components are implemented as Swift Packages
Packages are fully self-contained:
- Unit tests
- Mocks
- Even UI tests (where applicable)
Dependency management is handled entirely through Package.swift

Project Structure

App.swift only contains enough code to hand off the the first feature package which handles the entry/launch functionality before routing to the next package

Xcode Project
├── App/
│   └── App.swift
├── Feature Packages/ (local SPM)
│   └── ...
├── Shared Packages/ (local or remote SPM)
│   └── ...
├── Package Dependencies/ (3rd party SPM)
│   └── ...
├── AGENTS.md
└── Harness/

Feature Package Structure

Each feature is fully self-contained. Choose your preferred intra-package architecture such as MVVM-C or uni-directional

Package/
├── Package.swift
├── Sources
│   ├── Concurrent/
│   │   ├── Models/ (Sendable)
│   │   └── Service.swift (actor)
│   │
│   └── Main/ (UI layer)
│       ├── Views/
│       ├── PackageCoordinator.swift
│       └── PackageRoute.swift
│
└── Tests/

Harness

An harness is essential to accurate agentic contributions. The reference project include agentic harness documentation optimised for agents to accurately contribute features. As your project grows the harness must be maintained and optimised to remain effective

Concurrency Model

Swift Structured Concurrency can be difficult to adopt correctly, but when used well it provides significant benefits in predictability, stability and UI responsiveness.
Each feature package is split into two logical layers:

Main → @MainActor UI layer
Concurrent → isolated concurrency layer

This provides a clear separation between:

UI logic
Asynchronous / concurrent operations

Example responsibilities:

Main:
- Views
- Coordinators
- Routing logic
Concurrent:
- Services (actor)
- Models (Sendable)
- Other actors

Benefits

Scalability through clear module boundaries
Parallel development across agent-assisted teams
Faster CI by testing only affected packages
Single .xcodeproj (no .xcworkspace)
Agent-friendly, deterministic architecture

Dependency Management Recommendation

Avoid using:

Xcode → “Add Package Dependencies” UI

Why?

It mutates the .xcodeproj
Reduces source control clarity
Increases the likelihood of merge conflicts

Instead:

Declare dependencies explicitly in each Package.swift
Pin to exact versions of remote packages

This ensures:

Reproducible builds
Transparent dependency graphs
CI consistency

Reference Project

Explore the setup of the thin project, feature packages and the inter-package navigation with this reference project.

Included is a harness to allow agents to contribute features while adhering to the project's architectral patterns.

github.com/fraserscottmorrison/spm-modular-programming

Google provides an excellent reference Android project for a similarly modular architecture utilising gradle

github.com/android/nowinandroid

DEV Community: FraserScottMorrison