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→@MainActorUI 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
- Services (
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
Top comments (0)