SwiftUI Architecture Guide

Application Types

Applications are divided into Document-based and Library-based.

  • A document-based application stores user data in individual, standalone files. Users manually name and organize those files in a local system or synced cloud storage such as iCloud. The software typically opens multiple windows for different projects. This framing is for standalone, complex files that need to be shared, exported, or handled independently.
  • A library-based application manages data in one unified, central repository, locally or through remote cloud databases. Spotify, Netflix, and Notion are the examples shown. The file system is hidden; updates are saved automatically in real time; and a single window supports browsing, search, and access to the synchronized data collection from any device.

Model Types

Four model types: Data, Domain, Application, and Presentation.

Apple Platforms

In Apple MVC (AppKit / UIKit), the model branches to Data, Domain, and Presentation.

In SwiftUI, Model branches to Data and Domain.

Project Structure
SwiftUI App Folders

Swift Package Folders

App Modularization

Not every module in a large application needs to be extracted into a separate framework or Swift Package. Logical modularization can also be achieved through a well-organized folder structure within the main project. Introduce separate packages or frameworks only when there is a clear benefit, such as independent reuse, distribution, build isolation or ownership. Avoid unnecessary project and dependency management overhead.

State Management & Data Flow
  • Source of truth is “a key concept in SwiftUI”: a single place to store a piece of data, with everywhere else reading the same piece of data.
  • Environment is SwiftUI’s native dependency-injection mechanism. It allows shared dependencies, domain models, and services to be injected at the appropriate view-hierarchy level and accessed where needed without explicit parameter passing or unnecessary coupling. It is described as a tool for managing dependencies and sharing state across the view hierarchy.

Domain Model Ownership

Domain Models should be owned by the highest relevant SwiftUI view in the hierarchy that defines their context and lifecycle.

  • NavigationStack owns the Domain Models for its navigation context and makes them available to descendant views through @Environment.
  • When a NavigationStack is embedded in a TabView or NavigationSplitView, ownership moves up to the TabView or NavigationSplitView so the models can be shared across tabs or split views.

The stated result is clear ownership scope, sharing where needed, and isolation between independent navigation contexts.

Previews & UI Testing

Environment injection makes SwiftUI Previews and UI Tests easier to configure by allowing real Domain Models to be replaced with mock or dummy instances. Views can be tested independently with controlled data and predictable states, without requiring real services, network requests, or application setup.

Domain and Data Model Examples

For a library-based app with remote data.



Additional Domain Model Examples

E-commerce
Catalog, ShoppingCart, OrderHistory, Wishlist

Banking
MyAccounts, MyCards, MyTransactions, MyInvestments

Social Network
Feed, Conversations, Notifications, Friends

Healthcare
MyAppointments, MedicalHistory, Prescriptions, MyHealth

Education
Courses, MyCourses, Assignments, MyGrades, LearningProgress

Real Estate
PropertyCatalog, MyProperties, Favorites, Appointments

Hotel Booking
Destinations, Search, MyBookings, TravelHistory

Food Delivery
RestaurantCatalog, ShoppingCart, MyOrders, DeliveryTracking

Project Management
Projects, MyTasks, TeamMembers, Notifications

Insurance
MyPolicies, MyClaims, Coverage, Documents

Smart Home
MyHomes, Devices, Automations, EnergyUsage

Fitness
MyPlans, MyProgress, MyGoals, WorkoutHistory

Other
Search, Dashboard, Favorites, Notifications, Settings, ActivityHistory, Recommendations, Subscription, DocumentLibrary

ViewModel? - MVVM

In SwiftUI, the View encapsulates the UI content (body), its state (properties), and its actions or tasks (functions). This is possible because SwiftUI is designed around a declarative, state-driven UI model. In Android and .NET platforms, a separate ViewModel is typically required to hold and manage the View's state.

Projects that intoduce ViewModels in SwiftUI add unnecessary architectural complexity, boilerplate, and code duplication; synchronization issues; unclear state ownership; additional lifecycle management; more abstractions; harder debugging; and increased maintenance, without meaningful benefits over SwiftUI's native state management.

In UIKit, introducing a separate ViewModel layer is often unnecessary, as UIViewController already serves as the presentation model, handling presentation logic and coordinating the view. Non-UI responsibilities can be delegated to dedicated ModelControllers or Managers, avoiding unnecessary layers and abstractions.

Domain Models vs. ViewModels

Domain Models are view-independent, while ViewModels are view-dependent. A ViewModel is tightly coupled to the structure, state, and lifecycle of a specific View. Whenever the View code changes, its ViewModel often requires corresponding coding changes, and vice versa, creating additional maintenance and synchronization overhead.

Domain Models, on the other hand, represent application context and business functionality independently of the UI. This separation preserves UI independence and allows the same Domain Models to be shared across different screens and platforms, such as iPhone, iPhone Duo, iPad, and macOS, without duplicating or adapting business logic for each View.

This makes Domain Models a more scalable and maintainable approach for modern SwiftUI applications, particularly those targeting multiple screen sizes and platforms.

Data Access Patterns
Factory Method (recommended)

Very popular data access pattern in the MVC frameworks and Apple ecosystem.

Repository

Encouraged by Domain Driven Design (DDD).

Technologies & Modularization

Apple separates technologies into two layers:

  • Core: data access and services.
  • UI: user interface and user interaction.

Other Examples

Contacts + ContactsUI
Contact management.

Message + MessageUI
Messaging interface.

EventKit + EventKitUI
Calendar and reminders.

Photos + PhotosUI
Photo library and picker.

Speech + SpeechUI
Speech interface.

Testing
Today
  • Compared with back-end, many front-end unit tests provide little or no value, either testing nothing meaningful or merely validating mocks instead of actual code.
  • Tests remain more effective when made by humans or AI-agents.
  • Tests should not dictate the software architecture or replace the programmer's reasoning about the code it is building.

Swift already guarantees at compile time type safety, property and method existence, protocol conformance, optional handling, access control, initialization requirements, and concurrency safety (Swift 6). The diagrams therefore state that unit tests should not duplicate compiler-enforced checks, and should instead focus on runtime behaviour, business logic, edge cases, and potential regressions.

Automated testing should not drive unnecessary architectural complexity. There is no need to introduce multiple layers, protocols or abstractions solely to make code testable. Keep the architecture simple and introduce abstractions only when they provide genuine value, not just to accommodate testing.

Future
  • AI agents interact with the app or website like real users, executing predefined or exploratory user journeys across screens and platforms. They compare expected outcomes with actual behaviour to identify navigation failures, UI inconsistencies, broken interactions, unexpected errors, and deviations from expected workflows.
  • The AI agent reviews code changes for coding conventions, architecture consistency, potential bugs, edge cases, incorrect behaviour, broken dependencies, unintended side effects, code integrity, and regression risks, with the stated aim of keeping existing functionality intact.