iOS Architecture
Design data and capability boundaries that hide infrastructure without creating meaningless pass-through abstractions.
Before you begin
Learning stage
A repository presents domain data as a collection-like capability: fetch courses, observe progress, save a lesson completion. Callers ask in product language and do not need to know whether results come from HTTP, a database, memory, or a cache. A repository may coordinate several data sources and apply freshness or conflict rules.
A service represents a focused capability or operation that is not naturally collection-shaped, such as authentication, image processing, analytics, or certificate generation. A client is commonly a lower-level adapter for a protocol or system, such as an HTTP client. A use case coordinates a product workflow and may call repositories or services while applying policy.
Introduce a boundary when it hides a meaningful decision, supports replacement, or provides a stable domain vocabulary. A type that simply renames every API-client method adds indirection without isolation. Define error semantics, caching expectations, concurrency, and consistency at the boundary so callers know what the capability promises.
Learning stage
A repository actor owns remote-versus-cache decisions and returns domain values through one contract.
protocol CourseRepository: Sendable {
func courses(policy: LoadPolicy) async throws -> [Course]
func course(id: Course.ID) async throws -> Course
}
enum LoadPolicy: Sendable {
case remoteOnly
case cacheElseRemote
case refreshAfterCache
}
actor LiveCourseRepository: CourseRepository {
private let remote: any CourseRemoteDataSource
private let cache: any CourseCache
init(remote: any CourseRemoteDataSource, cache: any CourseCache) {
self.remote = remote
self.cache = cache
}
func courses(policy: LoadPolicy) async throws -> [Course] {
if policy != .remoteOnly, let cached = try await cache.readCourses(), !cached.isEmpty {
return cached
}
let courses = try await remote.fetchCourses()
try await cache.replaceCourses(with: courses)
return courses
}
func course(id: Course.ID) async throws -> Course {
if let cached = try await cache.readCourse(id: id) { return cached }
let course = try await remote.fetchCourse(id: id)
try await cache.save(course)
return course
}
}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
Define a progress repository that loads course progress, records completion, and supports offline use. Document identity, errors, and consistency expectations.
Hint: Write the contract in domain terms before choosing storage technologies.
Activity 2
Implement cache-first and remote-refresh policies behind one repository, then test stale cache, network failure, and successful refresh.
Hint: Decide which result the caller receives and when the cache changes.
Learning stage
Answer each question before revealing the explanation.
QUESTION 1
Domain-oriented data operations independent of storage details
The repository protects callers from transport, cache, and persistence decisions.
QUESTION 2
When it only renames and forwards another dependency without hiding decisions, stabilizing vocabulary, or enabling useful replacement.
Every boundary has navigation and maintenance cost, so it should earn that cost.
Learning stage
Explain the decision, dependency direction, trade-offs, and evidence—not only the pattern name.
Short answer: A repository provides domain-oriented access to entities; a service provides a focused operation or capability.
I use repositories when callers need a stable collection-like interface over remote or local data, often with caching and mapping. Services fit capabilities such as authentication or analytics. Use cases coordinate workflows across them. I avoid relying on suffixes and instead define the contract, policy, and reason the boundary exists.
Possible follow-ups
Learning stage
Repositories and services are valuable when they protect domain-facing code from infrastructure decisions and communicate clear behavioral contracts.