@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swiftui-patterns/references/architecture-patterns.md

@@ -1,145 +1,144 @@
 # Architecture Patterns
 
-## Contents
-- [MV Patterns](#mv-patterns)
-- [App Wiring and Dependency Graph](#app-wiring-and-dependency-graph)
-- [Lightweight Clients](#lightweight-clients)
-
-## MV Patterns
-
-Default to Model-View (MV) in SwiftUI. Views are lightweight state expressions; models and services own business logic. Do not introduce view models unless the existing code already requires them.
-
-### Contents
-
-- [Core Principles](#core-principles)
-- [Why Not MVVM](#why-not-mvvm)
-- [MV Pattern in Practice](#mv-pattern-in-practice)
-- [When a ViewModel Already Exists](#when-a-viewmodel-already-exists)
-- [When a New ViewModel Is Justified](#when-a-new-viewmodel-is-justified)
-- [Environment vs. Initializer Injection](#environment-vs-initializer-injection)
-- [Testing Strategy](#testing-strategy)
-- [Source](#source)
-
-### Core Principles
-
-- Views orchestrate UI flow using `@State`, `@Environment`, `@Query`, `.task`, and `.onChange`
-- Services and shared models live in the environment, are testable in isolation, and encapsulate complexity
-- Split large views into smaller subviews rather than introducing a view model
-- Test models, services, and business logic; views should stay simple and declarative
-
-### Why Not MVVM
+The reasoning behind the Model-View default, the cases where a view model still
+earns its place, and a reference wiring for the app shell.
 
-SwiftUI views are structs -- lightweight, disposable, and recreated frequently. Adding a ViewModel means fighting the framework's core design. Apple's own WWDC sessions (*Data Flow Through SwiftUI*, *Data Essentials in SwiftUI*, *Discover Observation in SwiftUI*) barely mention ViewModels.
-
-Every ViewModel adds:
-- More complexity and objects to synchronize
-- More indirection and cognitive overhead
-- Manual data fetching that duplicates SwiftUI/SwiftData mechanisms
-
-### MV Pattern in Practice
+## Contents
 
-#### View with Environment-Injected Service
+1. [MV Principles](#1-mv-principles)
+2. [Why Not MVVM](#2-why-not-mvvm)
+3. [MV in Practice](#3-mv-in-practice)
+4. [Working With an Existing View Model](#4-working-with-an-existing-view-model)
+5. [When a New View Model Is Justified](#5-when-a-new-view-model-is-justified)
+6. [Environment or Initializer Injection](#6-environment-or-initializer-injection)
+7. [Testing Strategy](#7-testing-strategy)
+8. [App Shell and Dependency Graph](#8-app-shell-and-dependency-graph)
+9. [Lightweight Clients](#9-lightweight-clients)
+10. [Further Reading](#10-further-reading)
+
+## 1. MV Principles
+
+- Views run the UI flow with `@State`, `@Environment`, `@Query`, `.task` and
+  `.onChange`.
+- Services and shared models live in the environment. Each one can be tested
+  on its own and keeps its complexity behind a small surface.
+- When a view gets big, extract subviews first. Add a view model only when the
+  existing code already depends on one.
+
+## 2. Why Not MVVM
+
+- A SwiftUI view is a struct that is cheap to build and rebuilt often. A view
+  model that mirrors it pushes against that design.
+- Apple's data-flow sessions barely mention view models: *Data Flow Through
+  SwiftUI* (WWDC19), *Data Essentials in SwiftUI* (WWDC20), *Discover
+  Observation in SwiftUI* (WWDC23).
+- Every view model adds cost: another object to keep in step with the view,
+  another hop to read through, and hand-written fetching that repeats what
+  SwiftUI and SwiftData already do.
+
+## 3. MV in Practice
+
+### A view backed by an environment service
 
 ```swift
-struct FeedView: View {
-    @Environment(FeedClient.self) private var client
-    @Environment(AppTheme.self) private var theme
-
-    enum ViewState {
-        case loading, error(String), loaded([Post])
+struct ArticlesView: View {
+    @Environment(NewsService.self) private var news
+    @Environment(Branding.self) private var branding
+
+    enum Phase {
+        case fetching
+        case failed(String)
+        case ready([Article])
     }
 
-    @State private var viewState: ViewState = .loading
-    @State private var isRefreshing = false
+    @State private var phase: Phase = .fetching
 
     var body: some View {
         NavigationStack {
             List {
-                switch viewState {
-                case .loading:
-                    ProgressView("Loading feed...")
+                switch phase {
+                case .fetching:
+                    ProgressView("Fetching articles")
                         .frame(maxWidth: .infinity)
                         .listRowSeparator(.hidden)
-                case .error(let message):
-                    ContentUnavailableView("Error", systemImage: "exclamationmark.triangle",
-                                           description: Text(message))
-                    .listRowSeparator(.hidden)
-                case .loaded(let posts):
-                    ForEach(posts) { post in
-                        PostRowView(post: post)
-                    }
+                case .failed(let reason):
+                    ContentUnavailableView("No articles",
+                                           systemImage: "wifi.exclamationmark",
+                                           description: Text(reason))
+                        .listRowSeparator(.hidden)
+                case .ready(let articles):
+                    ForEach(articles) { ArticleRow(article: $0) }
                 }
             }
             .listStyle(.plain)
-            .refreshable { await loadFeed() }
-            .task { await loadFeed() }
+            .refreshable { await fetch() }
+            .task { await fetch() }
         }
     }
 
-    private func loadFeed() async {
-        do {
-            let posts = try await client.getFeed()
-            viewState = .loaded(posts)
-        } catch {
-            viewState = .error(error.localizedDescription)
-        }
+    private func fetch() async {
+        do { phase = .ready(try await news.latest()) }
+        catch { phase = .failed(error.localizedDescription) }
     }
 }
 ```
 
-#### Using .task(id:) and .onChange
+### Modifiers as small reducers
 
-SwiftUI modifiers act as small state reducers:
+Treat `.task(id:)` and `.onChange` as tiny reducers: an input changes, a bit of
+state follows.
 
 ```swift
-.task(id: searchText) {
-    guard !searchText.isEmpty else { return }
-    await searchFeed(query: searchText)
+.task(id: filterText) {
+    guard !filterText.isEmpty else { return }
+    await runFilter(filterText)
 }
-.onChange(of: isInSearch, initial: false) {
-    guard !isInSearch else { return }
-    Task { await fetchSuggestedFeed() }
+.onChange(of: isFiltering, initial: false) { _, active in
+    if !active {
+        Task { await loadDefaultArticles() }
+    }
 }
 ```
 
-#### App-Level Environment Setup
+### Dependencies installed once at the app level
 
 ```swift
 @main
-struct MyApp: App {
-    @State var client = APIClient()
-    @State var auth = Auth()
-    @State var router = AppRouter(initialTab: .feed)
+struct NewsReaderApp: App {
+    @State private var news = NewsService()
+    @State private var session = SessionManager()
+    @State private var router = TabRouter(startTab: .today)
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
-                .environment(client)
-                .environment(auth)
+            RootView()
+                .environment(news)
+                .environment(session)
                 .environment(router)
         }
     }
 }
 ```
 
-All dependencies are injected once and available everywhere.
+Each dependency is created one time and every view below can reach it.
 
-#### SwiftData: The Perfect MV Example
+### SwiftData directly in views
 
-SwiftData was built to work directly in views:
+SwiftData is designed to be queried from views. Wrapping it in a view model
+means fetching and refreshing by hand, plus boilerplate.
 
 ```swift
-struct BookListView: View {
-    @Query private var books: [Book]
-    @Environment(\.modelContext) private var modelContext
+struct ShelfView: View {
+    @Query(sort: \Novel.title) private var novels: [Novel]
+    @Environment(\.modelContext) private var context
 
     var body: some View {
         List {
-            ForEach(books) { book in
-                BookRowView(book: book)
+            ForEach(novels) { novel in
+                NovelRow(novel: novel)
                     .swipeActions {
                         Button("Delete", role: .destructive) {
-                            modelContext.delete(book)
+                            context.delete(novel)
                         }
                     }
             }
@@ -148,150 +147,133 @@ struct BookListView: View {
 }
 ```
 
-Forcing a ViewModel here means manual fetching, manual refresh, and boilerplate everywhere.
-
-### When a ViewModel Already Exists
-
-If a ViewModel exists in the codebase:
-- Make it non-optional when possible
-- Pass dependencies via `init`, then forward them into the ViewModel in the view's `init`
-- Store as `@State` in the root view that owns it
-- Avoid `bootstrapIfNeeded` patterns
+## 4. Working With an Existing View Model
 
-```swift
-@State private var viewModel: SomeViewModel
-
-init(dependency: Dependency) {
-    _viewModel = State(initialValue: SomeViewModel(dependency: dependency))
-}
-```
+When the project already has view models, keep them tidy:
 
-Modern `@Observable` ViewModel with child-view binding:
+- Make the view model non-optional where you can.
+- Take dependencies in the view's `init` and hand them to the view model
+  there.
+- Hold the view model in `@State` in the view that owns it.
+- Skip lazy `bootstrapIfNeeded`-style setup.
 
 ```swift
-@MainActor @Observable final class ProfileViewModel {
-    var name: String = ""
-    var isSaving: Bool = false
-
-    private let client: ProfileClient
-
-    init(client: ProfileClient) {
-        self.client = client
-    }
-
-    func save() async throws {
-        isSaving = true
-        defer { isSaving = false }
-        try await client.update(name: name)
+@MainActor @Observable
+final class AccountEditorModel {
+    var displayName = ""
+    var isSubmitting = false
+    private let api: AccountAPI
+
+    init(api: AccountAPI) { self.api = api }
+
+    func submit() async throws {
+        isSubmitting = true
+        defer { isSubmitting = false }
+        try await api.rename(to: displayName)
     }
 }
 
-// Owner view creates via @State
-struct ProfileScreen: View {
-    @State private var viewModel: ProfileViewModel
+struct AccountEditorScreen: View {
+    @State private var model: AccountEditorModel
 
-    init(client: ProfileClient) {
-        _viewModel = State(initialValue: ProfileViewModel(client: client))
+    init(api: AccountAPI) {
+        _model = State(initialValue: AccountEditorModel(api: api))
     }
 
-    var body: some View {
-        ProfileForm(viewModel: viewModel)
-    }
+    var body: some View { AccountEditorForm(model: model) }
 }
 
-// Child view receives and binds
-struct ProfileForm: View {
-    @Bindable var viewModel: ProfileViewModel
+struct AccountEditorForm: View {
+    @Bindable var model: AccountEditorModel
 
     var body: some View {
-        TextField("Name", text: $viewModel.name)
-        Button("Save") { Task { try? await viewModel.save() } }
-            .disabled(viewModel.isSaving)
+        Form {
+            TextField("Display name", text: $model.displayName)
+            Button("Submit") {
+                Task { try? await model.submit() }
+            }
+            .disabled(model.isSubmitting)
+        }
     }
 }
 ```
 
-### When a New ViewModel Is Justified
-
-The MV pattern is the default. Introduce a ViewModel only when the view would be hard to read or test without one:
-
-- **Multi-step workflows**  -  onboarding, checkout, or wizard flows where each step mutates shared draft state
-- **Non-trivial business logic**  -  validation chains, derived state from multiple sources, or transformation pipelines that don't belong in a lightweight client
-- **Coordinated async streams**  -  the view orchestrates multiple publishers or `AsyncSequence` values with interdependent state transitions
-- **Existing test surface**  -  the codebase already tests against a ViewModel interface and rewriting to MV would be high cost, low reward
-
-The bar is "this view would be hard to read and test without a ViewModel," not "I'm used to MVVM."
+## 5. When a New View Model Is Justified
 
-### Environment vs. Initializer Injection
+Add one only when the view would otherwise be hard to read or hard to test.
+Cases that qualify:
 
-**Use `@Environment` when** the dependency is shared across many views at different depths. Threading it through every intermediate initializer adds noise:
-- App-wide services: auth, network client, theme, router
-- SwiftData `ModelContext`
-- Feature-scoped stores injected at a navigation root
+- Multi-step flows such as onboarding, checkout or a wizard, where every step
+  edits the same draft.
+- Real business logic: validation chains, state derived from several sources,
+  transformation pipelines that do not fit a lightweight client.
+- Coordinating several publishers or `AsyncSequence` streams whose transitions
+  depend on each other.
+- A code base that already tests against a view model interface, where moving
+  to MV would cost more than it returns.
 
-**Use initializer parameters when** the data is specific to this view instance. Makes the view's requirements explicit and keeps previews simple:
-- The selected item, filter mode, or configuration
-- Parent-to-child data that only one view needs
-- Values known at call site that don't change
+The test is readability and testability. Familiarity with MVVM from other
+platforms is not a reason.
 
-Rule of thumb: if three or more intermediate views would need to accept and forward a parameter just to reach a deeply nested consumer, move it to the environment.
+## 6. Environment or Initializer Injection
 
-### Testing Strategy
+Use `@Environment` for dependencies many views need at different depths:
 
-- Unit test services and business logic
-- Test models and transformations
-- Use SwiftUI previews for visual regression
-- Use UI automation for end-to-end tests
-- Views should be simple enough that they do not need dedicated unit tests
+- app-wide services: authentication, the network client, theme, router
+- the SwiftData `ModelContext`
+- a feature store installed at a navigation root
 
-### Source
+Use initializer parameters for data that belongs to one instance:
 
-Based on guidance from "SwiftUI in 2025: Forget MVVM" (Thomas Ricouard) and Apple WWDC sessions on SwiftUI data flow.
+- the selected item, a filter mode, a configuration value
+- data one child needs from its parent
+- values fixed at the call site
 
-## App Wiring and Dependency Graph
+Init parameters make requirements visible and keep previews simple. If three or
+more views in between would only forward a parameter, move it to the
+environment.
 
-### Contents
+## 7. Testing Strategy
 
-- [Intent](#intent)
-- [Recommended Structure](#recommended-structure)
-- [Root Shell Example](#root-shell-example)
-- [Dependency Graph Modifier](#dependency-graph-modifier)
-- [SwiftData / ModelContainer](#swiftdata-modelcontainer)
-- [Sheet Routing (Enum-Driven)](#sheet-routing-enum-driven)
-- [App Entry Point](#app-entry-point)
-- [Deep Linking](#deep-linking)
-- [When to Use](#when-to-use)
-- [Caveats](#caveats)
+- Unit test services and business rules.
+- Test models and data transformations.
+- Use SwiftUI previews to catch visual regressions.
+- Cover end-to-end flows with UI automation.
+- Keep views simple enough that they need no unit tests of their own.
 
-### Intent
+## 8. App Shell and Dependency Graph
 
-Wire the app shell (TabView + NavigationStack + sheets) and install a global dependency graph (environment objects, services, streaming clients, SwiftData ModelContainer) in one place.
+### Goal
 
-### Recommended Structure
+Wire the shell (tab view, navigation stacks, sheets) and install global
+dependencies (environment objects, services, streaming clients, the SwiftData
+`ModelContainer`) in one place:
 
-1. Root view sets up tabs, per-tab routers, and sheets.
-2. A dedicated view modifier installs global dependencies and lifecycle tasks (auth state, streaming watchers, push tokens, data containers).
-3. Feature views pull only what they need from the environment; feature-specific state stays local.
+1. The root view builds the tabs, one router per tab, and the sheets.
+2. One view modifier installs global dependencies and lifecycle work: auth
+   state, streaming watchers, push tokens, data containers.
+3. Feature views read only what they need from the environment. Feature state
+   stays inside the feature.
 
-### Root Shell Example
+### Root shell
 
 ```swift
 @MainActor
-struct AppView: View {
-    @State private var selectedTab: AppTab = .home
-    @State private var tabRouter = TabRouter()
+struct RootView: View {
+    @State private var currentTab: MainTab = .today
+    @State private var routers = TabRouter()
 
     var body: some View {
-        TabView(selection: $selectedTab) {
-            ForEach(AppTab.allCases) { tab in
-                let router = tabRouter.router(for: tab)
+        TabView(selection: $currentTab) {
+            ForEach(MainTab.allCases) { tab in
+                let router = routers.router(for: tab)
                 Tab(value: tab) {
-                    NavigationStack(path: tabRouter.binding(for: tab)) {
-                        tab.makeContentView()
+                    NavigationStack(path: routers.pathBinding(for: tab)) {
+                        tab.rootView()
                     }
-                    .withSheetDestinations(sheet: Binding(
-                        get: { router.presentedSheet },
-                        set: { router.presentedSheet = $0 }
+                    .presentsSheets(Binding(
+                        get: { router.activeSheet },
+                        set: { router.activeSheet = $0 }
                     ))
                     .environment(router)
                 } label: {
@@ -300,259 +282,286 @@ struct AppView: View {
             }
         }
         .tabBarMinimizeBehavior(.onScrollDown)
-        .withAppDependencyGraph()
+        .installAppServices()
     }
 }
 ```
 
-#### AppTab Enum
+`Tab(value:)` needs iOS 18; `.tabBarMinimizeBehavior(_:)` needs iOS 26.
 
 ```swift
 @MainActor
-enum AppTab: Identifiable, Hashable, CaseIterable {
-    case home, notifications, settings
-    var id: String { String(describing: self) }
+enum MainTab: Identifiable, Hashable, CaseIterable {
+    case today, alerts, preferences
+
+    nonisolated var id: String { String(describing: self) }
 
     @ViewBuilder
-    func makeContentView() -> some View {
+    func rootView() -> some View {
         switch self {
-        case .home: HomeView()
-        case .notifications: NotificationsView()
-        case .settings: SettingsView()
+        case .today: TodayView()
+        case .alerts: AlertsView()
+        case .preferences: PreferencesView()
         }
     }
 
     @ViewBuilder
     var label: some View {
         switch self {
-        case .home: Label("Home", systemImage: "house")
-        case .notifications: Label("Notifications", systemImage: "bell")
-        case .settings: Label("Settings", systemImage: "gear")
+        case .today: Label("Today", systemImage: "house")
+        case .alerts: Label("Alerts", systemImage: "bell")
+        case .preferences: Label("Preferences", systemImage: "gear")
         }
     }
 }
-```
 
-#### Router Skeleton
-
-```swift
-@MainActor
-@Observable
-final class RouterPath {
-    var path: [Route] = []
-    var presentedSheet: SheetDestination?
+@MainActor @Observable
+final class NavigationRouter {
+    var path: [Destination] = []
+    var activeSheet: SheetRoute?
 }
 
-enum Route: Hashable {
-    case detail(id: String)
+enum Destination: Hashable {
+    case article(id: String)
 }
 ```
 
-### Dependency Graph Modifier
+`TabRouter` is a small `@Observable` holder that keeps one `NavigationRouter`
+per tab and vends a `Binding` to each router's `path`.
+
+`MainTab` is `@MainActor` because it builds views, so its `id` is marked
+`nonisolated`; otherwise the `Identifiable` conformance would cross into
+main-actor code and Swift 6 rejects it.
 
-Use a single modifier to install environment objects and handle lifecycle hooks. This keeps wiring consistent and avoids forgetting a dependency at call sites.
+### Dependency graph modifier
+
+Install every environment object and lifecycle hook through one modifier. Call
+sites stay consistent and none of them can forget a dependency.
 
 ```swift
 extension View {
-    func withAppDependencyGraph(
-        client: APIClient = .shared,
-        auth: Auth = .shared,
-        theme: Theme = .shared,
-        toastCenter: ToastCenter = .shared
+    func installAppServices(
+        api: APIClient = .shared,
+        session: SessionManager = .shared,
+        branding: Branding = .shared,
+        banners: BannerCenter = .shared
     ) -> some View {
-        environment(client)
-            .environment(auth)
-            .environment(theme)
-            .environment(toastCenter)
-            .task(id: auth.currentAccount?.id) {
-                // Re-seed services when account changes
-                await client.configure(for: auth.currentAccount)
+        environment(api)
+            .environment(session)
+            .environment(branding)
+            .environment(banners)
+            .task(id: session.activeUser?.id) {
+                await api.prepare(for: session.activeUser)
             }
     }
 }
 ```
 
-Notes:
-- The `.task(id:)` hooks respond to account/client changes, re-seeding services and watcher state.
-- Keep the modifier focused on global wiring; feature-specific state stays within features.
-- Adjust types to match your project.
+The `.task(id:)` hook runs again when the signed-in account changes, so
+services and watchers are re-seeded for the new user. Keep this modifier to
+global wiring; feature state belongs to features. Rename the types to match the
+project.
 
-### SwiftData / ModelContainer
+### ModelContainer
 
-Install `ModelContainer` at the root so all feature views share the same store:
+Install the `ModelContainer` at the root so every feature shares one store:
 
 ```swift
 extension View {
-    func withModelContainer() -> some View {
-        modelContainer(for: [Draft.self, LocalTimeline.self, TagGroup.self])
+    func installDataStore() -> some View {
+        modelContainer(for: [Note.self, Folder.self, Attachment.self])
     }
 }
 ```
 
-A single container avoids duplicated stores per sheet or tab and keeps data consistent.
+A single container avoids a separate store per sheet or tab and keeps data
+consistent.
 
-### Sheet Routing (Enum-Driven)
+### Enum-driven sheets
 
-Centralize sheets with a small enum and a helper modifier:
+Keep every sheet in one small `Identifiable` enum plus a helper modifier:
 
 ```swift
-enum SheetDestination: Identifiable {
-    case composer
-    case settings
-    var id: String { String(describing: self) }
+enum SheetRoute: Identifiable {
+    case newPost
+    case accountSettings
+
+    var id: Self { self }
 }
 
 extension View {
-    func withSheetDestinations(sheet: Binding<SheetDestination?>) -> some View {
-        sheet(item: sheet) { destination in
-            switch destination {
-            case .composer:
-                ComposerView().withEnvironments()
-            case .settings:
-                SettingsView().withEnvironments()
+    func presentsSheets(_ route: Binding<SheetRoute?>) -> some View {
+        sheet(item: route) { route in
+            switch route {
+            case .newPost: NewPostView().installAppServices()
+            case .accountSettings: AccountSettingsView().installAppServices()
             }
         }
     }
 }
 ```
 
-Enum-driven sheets keep presentation centralized and testable; adding a new sheet means one enum case and one switch branch.
+A new sheet costs one case and one branch. Presentation stays in one place and
+is easy to test. Sheets start a new presentation context, so each one applies
+the dependency modifier again.
 
-### App Entry Point
+### App entry point
 
 ```swift
 @main
-struct MyApp: App {
-    @State var client = APIClient()
-    @State var auth = Auth()
-    @State var router = AppRouter(initialTab: .home)
+struct FieldNotesApp: App {
+    @State private var api = APIClient.shared
+    @State private var session = SessionManager.shared
 
     var body: some Scene {
         WindowGroup {
-            AppView()
-                .environment(client)
-                .environment(auth)
-                .environment(router)
+            RootView()
+                .environment(api)
+                .environment(session)
+                .installDataStore()
         }
     }
 }
 ```
 
-### Deep Linking
+### Deep links
 
-Store `NavigationPath` as `Codable` for state restoration. Handle incoming URLs with `.onOpenURL`:
+- For state restoration, save the navigation path. `NavigationPath.codable`
+  gives a `Codable` representation when every element is `Codable`.
+- Handle incoming URLs with `.onOpenURL`:
 
 ```swift
 .onOpenURL { url in
-    guard let route = Route(from: url) else { return }
-    router.navigate(to: route)
+    guard let destination = Destination(url: url) else { return }
+    router.path.append(destination)
 }
 ```
 
-See the `swiftui-navigation` skill for full URL routing patterns.
+Complete URL routing is covered in `swiftui-navigation`.
 
-### When to Use
+### When this structure fits
 
-- Apps with multiple packages/modules that share environment objects and services
-- Apps that need to react to account/client changes and rewire streaming/push safely
-- Any app that wants consistent TabView + NavigationStack + sheet wiring without repeating environment setup
+- Several packages or modules share the same environment objects and services.
+- The app has to react to account or client changes and rewire streaming or
+  push safely.
+- You want tabs, navigation stacks and sheets wired the same way everywhere
+  without repeating environment setup.
 
 ### Caveats
 
-- Keep the dependency modifier slim; do not put feature state or heavy logic there
-- Ensure `.task(id:)` work is lightweight or cancelled appropriately; long-running work belongs in services
-- If unauthenticated clients exist, gate streaming/watch calls to avoid reconnect spam
-
-## Lightweight Clients
+- Keep the dependency modifier slim: no feature state, no heavy logic.
+- Work in `.task(id:)` must be short or cancel cleanly. Long-running work
+  belongs in services.
+- When a client can exist without a signed-in user, gate streaming and watch
+  calls so the app does not fall into a reconnect loop.
 
-Use this pattern to keep networking or service dependencies simple and testable without introducing a full view model or heavy DI framework. It works well for SwiftUI apps where you want a small, composable API surface that can be swapped in previews/tests.
+## 9. Lightweight Clients
 
-### Intent
-- Provide a tiny "client" type made of async closures.
-- Keep business logic in a store or feature layer, not the view.
-- Enable easy stubbing in previews/tests.
+A client can be a plain struct of async closures. There is no view model and
+no DI framework, the view never sees networking, and previews or tests swap in
+a stub. Business logic sits in a store or feature layer.
 
-### Minimal shape
 ```swift
-struct SomeClient {
-    var fetchItems: (_ limit: Int) async throws -> [Item]
-    var search: (_ query: String, _ limit: Int) async throws -> [Item]
-}
-
-extension SomeClient {
-    static func live(baseURL: URL = URL(string: "https://example.com")!) -> SomeClient {
-        let session = URLSession.shared  // Prototyping only. For production, create a URLSession with timeoutIntervalForRequest: 30, timeoutIntervalForResource: 300, waitsForConnectivity: true, and a URLCache.
-        return SomeClient(
-            fetchItems: { limit in
-                // build URL, call session, decode
+struct CatalogClient {
+    var products: (_ page: Int) async throws -> [Product]
+    var lookup: (_ term: String, _ page: Int) async throws -> [Product]
+
+    static func live(host: URL) -> CatalogClient {
+        let session = URLSession(configuration: .catalog)
+        return CatalogClient(
+            products: { page in
+                let url = host.appending(path: "products")
+                    .appending(queryItems: [URLQueryItem(name: "page", value: String(page))])
+                let (data, _) = try await session.data(from: url)
+                return try JSONDecoder().decode([Product].self, from: data)
             },
-            search: { query, limit in
-                // build URL, call session, decode
+            lookup: { term, page in
+                let url = host.appending(path: "search")
+                    .appending(queryItems: [
+                        URLQueryItem(name: "q", value: term),
+                        URLQueryItem(name: "page", value: String(page))
+                    ])
+                let (data, _) = try await session.data(from: url)
+                return try JSONDecoder().decode([Product].self, from: data)
             }
         )
     }
 }
+
+extension URLSessionConfiguration {
+    static var catalog: URLSessionConfiguration {
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 30
+        config.timeoutIntervalForResource = 300
+        config.waitsForConnectivity = true
+        config.urlCache = URLCache(memoryCapacity: 10_000_000, diskCapacity: 50_000_000)
+        return config
+    }
+}
 ```
 
-### Usage pattern
+`URLSession.shared` is fine for a prototype. Production code builds its own
+session as above: 30 second request timeout, 300 second resource timeout,
+`waitsForConnectivity` on, and a `URLCache`.
+
 ```swift
-@MainActor
-@Observable final class ItemsStore {
-    enum LoadState { case idle, loading, loaded, failed(String) }
+@MainActor @Observable
+final class CatalogStore {
+    enum Status { case idle, loading, loaded, failed(String) }
 
-    var items: [Item] = []
-    var state: LoadState = .idle
-    private let client: SomeClient
+    var status: Status = .idle
+    var products: [Product] = []
+    private let client: CatalogClient
 
-    init(client: SomeClient) {
-        self.client = client
-    }
+    init(client: CatalogClient) { self.client = client }
 
-    func load(limit: Int = 20) async {
-        state = .loading
+    func load(page: Int = 1) async {
+        status = .loading
         do {
-            items = try await client.fetchItems(limit)
-            state = .loaded
+            products = try await client.products(page)
+            status = .loaded
         } catch {
-            state = .failed(error.localizedDescription)
+            status = .failed(error.localizedDescription)
         }
     }
 }
-```
 
-```swift
-struct ContentView: View {
-    @Environment(ItemsStore.self) private var store
+struct CatalogView: View {
+    @Environment(CatalogStore.self) private var store
 
     var body: some View {
-        List(store.items) { item in
-            Text(item.title)
-        }
-        .task { await store.load() }
+        List(store.products) { ProductRow(product: $0) }
+            .task { await store.load() }
     }
 }
-```
 
-```swift
 @main
-struct MyApp: App {
-    @State private var store = ItemsStore(client: .live())
+struct ShopApp: App {
+    @State private var store = CatalogStore(client: .live(host: AppConfig.apiHost))
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
-                .environment(store)
+            CatalogView().environment(store)
         }
     }
 }
 ```
 
-### Guidance
-- Keep decoding and URL-building in the client; keep state changes in the store.
-- Make the store accept the client in `init` and keep it private.
-- Avoid global singletons; use `.environment` for store injection.
-- If you need multiple variants (mock/stub), add `static func mock(...)`.
+Guidelines:
+
+- URL building and decoding live in the client. State changes live in the
+  store.
+- The store receives the client in `init` and keeps it `private`.
+- No global singletons for stores; install them with `.environment`.
+- Add `static func mock(...)` factories for stubbed variants.
+
+Pitfalls:
+
+- UI state kept in the client. It belongs in the store.
+- Client closures that capture `self` or view state.
+
+## 10. Further Reading
 
-### Pitfalls
-- Don't put UI state in the client; keep state in the store.
-- Don't capture `self` or view state in the client closures.
+- "SwiftUI in 2025: Forget MVVM" by Thomas Ricouard, the article this MV
+  guidance follows.
+- The WWDC data-flow sessions listed in [Why Not MVVM](#2-why-not-mvvm).