iOS Architecture
Organize source code around product capabilities while preserving clear app, feature, domain, and shared boundaries.
Before you begin
Learning stage
Type-first organization places every view controller, model, and service in application-wide buckets. It looks tidy in a small project but scatters one product feature across distant directories. Feature-first organization keeps code that changes together close: CourseList can contain its view, presentation model, routes, and feature-specific models.
The application layer owns composition, scene setup, top-level routing, and environment selection. Feature folders own user-visible capabilities. Domain or core areas hold genuinely cross-feature policy, while infrastructure contains concrete system adapters. Shared UI should include stable reusable components, not every view used twice.
Folders communicate intent but do not enforce dependency rules. Begin with namespaces, access control, review conventions, and tests. Extract a Swift package or target only when build isolation, ownership, reuse, dependency enforcement, or build performance makes the extra boundary worthwhile.
Learning stage
This tree keeps feature code together while making composition and truly shared capabilities visible.
LearningApp/
├── App/
│ ├── LearningApp.swift
│ ├── AppDependencies.swift
│ └── AppCoordinator.swift
├── Features/
│ ├── CourseLibrary/
│ │ ├── CourseLibraryView.swift
│ │ ├── CourseLibraryModel.swift
│ │ ├── CourseLibraryRoute.swift
│ │ └── CourseLibraryTests.swift
│ └── LessonPlayer/
│ ├── LessonPlayerViewController.swift
│ ├── LessonPlayerViewModel.swift
│ └── LessonPlayerTests.swift
├── Core/
│ ├── LearningModels/
│ └── ProgressRules/
├── Infrastructure/
│ ├── Networking/
│ └── Persistence/
└── DesignSystem/
├── Components/
└── Tokens/Learning stage
Connect the architectural concept to maintainable iOS features and real change scenarios.
Learning stage
Identify abstractions and dependencies that add coupling, ambiguity, or unnecessary ceremony.
Learning stage
Apply the design to a small feature and evaluate it through observable change scenarios.
Activity 1
Move a sample project's Controllers, Views, ViewModels, and Services into app, feature, core, infrastructure, and design-system areas. Explain each ambiguous placement.
Hint: Place code with the feature that owns its change until cross-feature reuse is proven.
Activity 2
Review every item in a Shared folder and classify it as stable cross-feature API, feature-owned code, infrastructure, or accidental convenience.
Hint: Two uses are evidence to examine, not automatic proof of a shared abstraction.
Learning stage
Answer each question before revealing the explanation.
QUESTION 1
Code that changes for one product capability stays close together
Cohesion improves discovery, ownership, and the ability to change or remove a feature.
QUESTION 2
No. They communicate intent, while modules, access control, tests, and tooling provide stronger enforcement.
Any source in one app target can usually reference another internal type regardless of its folder.
Learning stage
Explain the decision, dependency direction, trade-offs, and evidence—not only the pattern name.
Short answer: Primarily by product feature, with small explicit app, domain, infrastructure, and design-system areas.
I keep feature presentation, routes, and tests together, define ownership for shared domain values, and prevent Shared from becoming a dumping ground. I begin with logical boundaries and access control, then extract modules only when they improve build isolation, ownership, reuse, or dependency enforcement enough to justify their cost.
Possible follow-ups
Learning stage
Feature-based organization aligns the source tree with product change, while deliberate shared areas and later module boundaries keep coupling visible.