Swift / SwiftUI iOS

Build native iOS apps with SwiftUI, Observation, and Swift concurrency. The app consumes the same API as the web and Expo apps. Targets Swift 6 language mode and iOS 17+ (Observation). If the deployment target is lower, adapt the Observation rules to ObservableObject.

Choose native Swift over Expo when the product needs deep platform integration (widgets and Live Activities as core features, watchOS, heavy media or AR, advanced background modes) or an existing native codebase. The decision belongs in the architecture doc (see fullstack-architect).

When to use

• Writing SwiftUI views, navigation, or @Observable models.
• Networking with URLSession, auth flows, or token storage.
• Concurrency work: async/await, tasks, actors, Sendable diagnostics.
• In-app purchases and subscriptions with StoreKit 2.
• Tests, TestFlight, App Store submission, review rejections.

Core rules

1. Views are functions of state. Logic, loading, and side effects live in @MainActor @Observable models and services, never in body or a view's init. Views get recreated constantly.
2. Swift concurrency only. Use async/await, structured tasks, and actors for new code. Wrap legacy callback APIs once with withCheckedThrowingContinuation. Don't use DispatchQueue in new code except for interop.
3. Swift 6 strict concurrency. Fix Sendable and isolation diagnostics properly. @unchecked Sendable and nonisolated(unsafe) need a comment that proves safety, or they don't merge.
4. UI state is MainActor-isolated. Shared mutable non-UI state (API client, token store, caches) lives in actors.
5. Credentials live only in the Keychain. Never in UserDefaults, files, or @AppStorage. No secrets compiled into the binary: anything in the IPA can be extracted.
6. The server is the source of truth for authorization and entitlements. The client caches them for UX.
7. Every screen handles loading, empty, error-with-retry, and success. Cancellation is not an error: don't show alerts for CancellationError or URLError.cancelled.

Architecture

App/
├── AcmeApp.swift              # @main, composition root: builds services, injects via .environment
├── Core/                      # move to a local Swift package as the app grows (faster builds, enforced boundaries)
│   ├── Networking/            # APIClient (actor), Endpoint, APIError, JSON coding
│   ├── Auth/                  # TokenStore (actor, Keychain), SessionModel (@Observable)
│   ├── Purchases/             # StoreKit 2 wrapper, entitlement sync with the API
│   └── Persistence/           # SwiftData/GRDB cache, if offline is needed (a cache, not the source of truth)
├── Features/
│   └── Events/
│       ├── EventsView.swift
│       ├── EventsModel.swift  # @MainActor @Observable
│       └── EventRow.swift
├── DesignSystem/              # reusable components, typography, colors
└── Resources/                 # Assets, Localizable.xcstrings, PrivacyInfo.xcprivacy

• Dependency injection: build services in the composition root and pass them through initializers or .environment(_:). No global singletons (APIClient.shared) reached from deep inside features. They make tests and previews hard.
• Navigation: NavigationStack(path:) with value-based navigationDestination(for:), and a router model that owns the path. Deep links and notification taps append to the path.

Preferred patterns

@MainActor @Observable
final class EventsModel {
    enum State { case loading, empty, loaded([Event]), failed(String) }

    private(set) var state: State = .loading
    private var nextCursor: String?
    private let api: APIClient

    init(api: APIClient) { self.api = api }

    func load() async {
        state = .loading
        do {
            let page = try await api.send(.upcomingEvents(cursor: nil))
            nextCursor = page.nextCursor
            state = page.items.isEmpty ? .empty : .loaded(page.items)
        } catch is CancellationError {
            // the view went away; keep the current state
        } catch {
            state = .failed(error.userMessage)
        }
    }
}

struct EventsView: View {
    @State private var model: EventsModel

    init(api: APIClient) { _model = State(initialValue: EventsModel(api: api)) }

    var body: some View {
        content
            .task { await model.load() }          // starts on appear, cancels on disappear
            .refreshable { await model.load() }
    }

    @ViewBuilder private var content: some View {
        switch model.state {
        case .loading: ProgressView()
        case .empty: ContentUnavailableView("No upcoming events", systemImage: "calendar")
        case .loaded(let events): List(events) { EventRow(event: $0) }
        case .failed(let message):
            ContentUnavailableView {
                Label("Couldn't load events", systemImage: "wifi.exclamationmark")
            } description: { Text(message) } actions: {
                Button("Try again") { Task { await model.load() } }
            }
        }
    }
}

• Observation: own models with @State, pass them down as plain properties, and use @Bindable when a child needs bindings. Use @Environment for app-wide services. Don't use ObservableObject/@Published/@StateObject in new iOS 17+ code.
• Async work in views: use .task { }, or .task(id: query) to restart when an input changes. Don't use onAppear { Task { ... } }, which never cancels.
• Networking: one APIClient actor with a configured URLSession (timeouts, waitsForConnectivity where appropriate) and one JSONDecoder. It attaches the bearer token, maps Problem Details errors to a typed APIError using the API's code, and on 401 runs a single-flight token refresh, then retries once.
• Dates: the API returns ISO 8601 UTC with fractional seconds (Pydantic emits microseconds). JSONDecoder.DateDecodingStrategy.iso8601 rejects fractional seconds, so use a custom strategy and test it with a fixture captured from the real API.
• Keychain: generic password items with kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly (use WhenUnlockedThisDeviceOnly if nothing refreshes in the background). Keychain items survive app deletion, so wipe them on the first launch after a fresh install.
• Sign in: use Sign in with Apple (SignInWithAppleButton) or Google via ASWebAuthenticationSession/SwiftUI's webAuthenticationSession, with PKCE. Send the identity token to the API, which verifies it and issues its own tokens.

Networking and Keychain implementations are in references/networking-and-keychain.md. StoreKit 2 with server-side entitlements is in references/storekit.md.

Patterns to avoid

Debugging

• Concurrency: enable Thread Sanitizer and the Main Thread Checker in the scheme, and read Swift 6 diagnostics as design feedback. A data race warning means shared mutable state without an owner.
• Unexpected view updates: call let _ = Self._printChanges() in body (debug builds only). Use the SwiftUI instrument to find expensive or frequent body evaluations.
• Decoding failures: print DecodingError cases in full (key path + debug description). The usual causes are date formats, nulls where non-optional, and unknown enum values (decode unknown cases to an .unknown fallback).
• Network: log the API's X-Request-ID response header with every failure, so backend logs can be correlated. Inspect traffic with Proxyman or Charles in debug builds.
• Memory: Instruments Leaks/Allocations. Closures stored on models need [weak self]. A closure passed to an async call usually doesn't.
• Crashes: upload dSYMs from CI (Xcode Cloud and fastlane can do this as part of the build) and read symbolicated reports in Xcode Organizer or your crash reporter.

Performance

• Use List or LazyVStack with stable identifiers for long content. Paginate with the API cursor.
• Request thumbnail sizes from the server. AsyncImage has no tunable cache, so use a caching loader for image-heavy lists.
• Keep body cheap: precompute display strings in the model, and use FormatStyle instead of creating formatters in body.
• Observation tracks properties per access. Small subviews that read only what they show re-render less.
• Measure launch with the App Launch instrument and defer non-critical setup until after first frame.

Security

• Keychain with ThisDeviceOnly accessibility. Clear the Keychain, URLCache, and local stores on sign-out.
• App Transport Security stays on. No arbitrary loads.
• Use os.Logger: interpolated values are private by default. Mark only non-sensitive values privacy: .public.
• Write sensitive files with .completeFileProtection.
• Validate universal link and notification payloads before navigating or acting.
• Jailbreak detection is not a control. Server-side authorization is.

Testing

• Swift Testing (@Test, #expect, #require, parameterized tests) for models, decoding, and the API client. Use XCTest for UI tests (XCUITest) and performance tests.
• API client: stub responses with a URLProtocol subclass. Test request building, decoding of real captured fixtures, Problem Details error mapping, and 401 → single refresh → retry → sign-out.
• Models: inject a fake API (protocol or closure-based) and assert state transitions: loading → loaded, empty, failed, and cancellation ignored.
• StoreKit: a StoreKit configuration file plus SKTestSession for purchase, renewal, refund, and Ask to Buy flows.
• Manual matrix: the oldest supported iOS, the smallest device, the largest Dynamic Type size, VoiceOver on core flows, dark mode, and offline.

App Store workflow

• Versions: CFBundleShortVersionString is the marketing version (bump it per release). CFBundleVersion is the build number (monotonic, set by CI).
• CI: Xcode Cloud, or fastlane on your CI with managed signing (match), produces signed builds and uploads them to TestFlight.
• TestFlight: internal testers first. External groups need beta app review.
• Release: use phased release for automatic updates. Pause it if crash rates rise.
• Privacy: PrivacyInfo.xcprivacy declares required-reason APIs (e.g. UserDefaults, file timestamps) and any tracking domains. Third-party SDKs must ship their own manifests. App Privacy labels in App Store Connect must match real data collection.
• Common rejection causes: no in-app account deletion when accounts can be created; third-party login without an equivalent privacy-focused option such as Sign in with Apple; digital goods sold outside in-app purchase where the storefront rules don't allow it (these rules differ by region and have changed recently, so check current guideline 3.1); user-generated content without reporting, blocking, and filtering; vague permission purpose strings; no demo account for review.
• Apple raises the minimum Xcode/SDK for uploads periodically. Keep CI on a current Xcode.

Production-readiness checklist

• Swift 6 language mode. No unexplained @unchecked Sendable or nonisolated(unsafe).
• Tokens are in the Keychain (ThisDeviceOnly), wiped on sign-out and on first launch after reinstall.
• Every screen handles loading, empty, error-with-retry, and offline. Cancellations are silent.
• The API client decodes captured fixtures, including dates with fractional seconds and unknown enum values.
• 401 → single refresh → one retry → sign-out, covered by tests.
• StoreKit: Transaction.updates listener started at launch, transactions finished after granting, entitlements verified server-side, a Restore Purchases button exists.
• Privacy manifest, App Privacy labels, and purpose strings are accurate. Account deletion exists.
• dSYMs are uploaded and crash reporting is verified with a test crash.
• Accessibility pass (Dynamic Type, VoiceOver labels). Tested on the oldest supported iOS.
• CI-managed build numbers, a TestFlight pass before every release, phased release enabled.