{ "id": "swift-swiftui-ios", "name": "Native iOS: Swift + SwiftUI", "use_cases": [ "iPhone and iPad products", "Native Apple integrations", "Accessible mobile clients for a shared service" ], "choose_when": [ "Apple-native UI and platform capabilities are requirements", "A Mac/Xcode build environment and Apple distribution ownership are available" ], "avoid_when": [ "The requirement is a single shared UI across iOS and Android", "There is no supported macOS/Xcode build environment" ], "tools": [ { "job": "UI and state", "default": "SwiftUI + Observation; small @MainActor observable presentation models; explicit services", "alternatives": [ "UIKit for unsupported UI or existing UIKit apps; ObservableObject for older deployment targets" ], "reason": "Native controls and platform conventions; keep domain and transport logic out of views", "limits": "SwiftUI/Observation availability must match the minimum OS; Observation is not persistence or automatic thread safety", "source_urls": [ "https://developer.apple.com/swiftui/", "https://developer.apple.com/documentation/swiftui/model-data" ] }, { "job": "Structured local persistence", "default": "SwiftData", "alternatives": [ "Core Data for established stores or older targets; explicit SQLite for requirements SwiftData does not meet" ], "reason": "Framework-integrated models and persistence with a small dependency footprint", "limits": "Validate migrations, relationship behavior and deployment availability; local persistence does not implement cross-platform sync", "source_urls": [ "https://developer.apple.com/documentation/swiftdata/modelcontext" ] }, { "job": "Nonsecret preferences", "default": "UserDefaults", "alternatives": [ "Existing explicit nonsecret preferences storage; structured databases have a separate persistence job" ], "reason": "Framework-integrated models and persistence with a small dependency footprint", "limits": "Validate migrations, relationship behavior and deployment availability; local persistence does not implement cross-platform sync", "source_urls": [ "https://developer.apple.com/documentation/swiftdata/modelcontext" ] }, { "job": "Networking and API contract", "default": "URLSession + Codable behind an injected API client", "alternatives": [ "Generated Swift client from a versioned API contract when its generator is proven" ], "reason": "Native HTTP client and async APIs; share API schemas and fixtures with Android", "limits": "Check status codes, cancellation, timeouts and decoding; do not put provider secrets in the client; server owns authorization", "source_urls": [ "https://developer.apple.com/documentation/foundation/urlsession" ] }, { "job": "Concurrency and background work", "default": "Swift structured concurrency, cancellation and actor isolation; server for durable agent runs", "alternatives": [ "BackgroundTasks or background URLSession for eligible OS-managed local work" ], "reason": "Keep rendering responsive and avoid tying durable business work to a view lifetime", "limits": "async does not mean CPU work runs off the main actor; OS may suspend apps and does not guarantee exact background scheduling", "source_urls": [ "https://developer.apple.com/documentation/foundation/urlsession", "https://developer.apple.com/documentation/backgroundtasks" ] }, { "job": "Credentials", "default": "Keychain for app credentials", "alternatives": [ "In-memory credentials when persistence is unnecessary" ], "reason": "Use platform secret storage rather than preferences or database fields", "limits": "Define accessibility and logout/revocation behavior; backend service credentials never belong in app binaries", "source_urls": [ "https://developer.apple.com/documentation/security/keychain-services" ] }, { "job": "Unit and integration tests", "default": "Swift Testing for new domain/API tests; XCTest where needed", "alternatives": [ "Keep established XCTest suites" ], "reason": "Test deterministic state transitions, fixtures, decoding, persistence and failures", "limits": "Do not mix Swift Testing and XCTest assertions inside a single test; simulator tests do not validate all hardware behavior", "source_urls": [ "https://developer.apple.com/documentation/xcode/testing" ] }, { "job": "UI and accessibility", "default": "XCTest/XCUIAutomation; per-screen accessibility audits; VoiceOver and Dynamic Type review", "alternatives": [ "Accessibility Inspector for interactive audit" ], "reason": "Exercise navigation, permission states, keyboard/focus, screen-reader order and large text", "limits": "Automated audits cover the current screen and do not establish usability or complete accessibility; hardware checks remain necessary", "source_urls": [ "https://developer.apple.com/documentation/xcode/testing", "https://developer.apple.com/documentation/accessibility/performing-accessibility-audits-for-your-app" ] }, { "job": "Build, CI and distribution", "default": "Xcode + Swift Package Manager; xcodebuild on pinned macOS/Xcode CI; TestFlight before App Store", "alternatives": [ "Xcode Cloud for managed Apple CI" ], "reason": "One reproducible toolchain, recorded test results, signed archives and beta verification", "limits": "Mac and compatible SDK/runtime required; signing team, bundle ID, profiles, capabilities, account access and store submission remain explicit handoffs; archive success is not publication", "source_urls": [ "https://developer.apple.com/xcode-cloud/", "https://developer.apple.com/library/archive/technotes/tn2339/_index.html" ] }, { "job": "Navigation", "default": "SwiftUI NavigationStack", "alternatives": [ "Preserve an existing compatible project choice" ], "reason": "Platform navigation keeps back behavior and destinations in native UI", "limits": "Use on supported OS versions; keep route identities separate from loaded objects and test deep-link/session restoration. iOS 16+ availability requires a plan for older targets.", "source_urls": [ "https://developer.apple.com/documentation/swiftui/navigationstack" ] }, { "job": "Notifications", "default": "UserNotifications", "alternatives": [ "Preserve an existing compatible project choice" ], "reason": "Native notifications support reminders with explicit user permission", "limits": "Request authorization in context, handle denied/revoked permission and validate notification routes. Remote delivery adds APNs/server setup; delivery timing is not a durable job guarantee.", "source_urls": [ "https://developer.apple.com/documentation/usernotifications/asking-permission-to-use-notifications" ] }, { "job": "Media selection", "default": "PhotosUI PhotosPicker", "alternatives": [ "Preserve an existing compatible project choice" ], "reason": "Native picker lets users choose image/video assets", "limits": "iOS 16+; load selected representations with cancellation/error handling and bound file size before upload. Selection is not immediate local-file availability.", "source_urls": [ "https://developer.apple.com/documentation/photosui/photospicker" ] } ], "setup_steps": [ "Start in a source checkout in a local development workspace. Record minimum iOS/iPadOS versions, bundle ID, required capabilities, API schema and signing owner.", "Install a compatible stable Xcode and required simulator runtimes; finish Apple license/platform setup through the accountable operator. Record xcodebuild -version and selected developer directory.", "Create an iOS App in Xcode using Swift and SwiftUI, with unit and UI test targets. Share the scheme. Pin package resolution; use only dependencies justified by a requirement.", "Separate views, observable presentation state, repositories and API DTOs. Add migration fixtures and versioned network fixtures; use a fake API for tests.", "Run local simulator checks and CI using an actual destination ID. Then verify representative physical devices, offline/reconnect, permissions, VoiceOver and large text.", "Have the account owner establish team/bundle ID/capabilities and signing access. Produce a signed archive, verify a TestFlight install, then follow the authorized release workflow. Retain result bundles and release evidence." ], "verification_commands": [ "xcodebuild -version", "xcode-select -p", "xcodebuild -list -project App.xcodeproj", "xcodebuild -showdestinations -project App.xcodeproj -scheme App", "xcodebuild -resolvePackageDependencies -project App.xcodeproj -scheme App", "xcodebuild test -project App.xcodeproj -scheme App -destination \"platform=iOS Simulator,id=\" -resultBundlePath .xcresult", "xcodebuild archive -project App.xcodeproj -scheme App -destination \"generic/platform=iOS\" -archivePath .xcarchive", "xcodebuild -exportArchive -archivePath .xcarchive -exportPath -exportOptionsPlist .plist" ], "evidence_status": "documentation-reviewed", "sources": [ { "url": "https://developer.apple.com/swiftui/", "title": "SwiftUI", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/swiftui/model-data", "title": "SwiftUI model data", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/swiftdata/modelcontext", "title": "SwiftData ModelContext", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/foundation/urlsession", "title": "URLSession", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/xcode/testing", "title": "Testing with Xcode", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/accessibility/performing-accessibility-audits-for-your-app", "title": "Performing accessibility audits", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/xcode-cloud/", "title": "Xcode Cloud", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/library/archive/technotes/tn2339/_index.html", "title": "Xcode command-line FAQ (archived; check local help)", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/security/keychain-services", "title": "Keychain services", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/backgroundtasks", "title": "Background Tasks", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/swiftui/navigationstack", "title": "SwiftUI NavigationStack", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/usernotifications/asking-permission-to-use-notifications", "title": "Apple notification permission", "checked_date": "2026-10-10" }, { "url": "https://developer.apple.com/documentation/photosui/photospicker", "title": "PhotosPicker", "checked_date": "2026-10-10" } ], "open_questions": [ "What minimum OS versions, device matrix and Apple capabilities must be supported?", "Which offline/sync/conflict rules and API contract apply?", "Do notifications/media selection require permission-denied and degraded flows?", "Who owns bundle identity, signing and beta/release distribution?" ], "title": "Swift + SwiftUI", "language": "Swift", "group": "Native mobile", "kind": [ "ios" ], "ui": "native", "host": "native", "summary": "Native iPhone and iPad apps using Apple's UI and platform APIs.", "shape": "SwiftUI · Swift concurrency · SwiftData · Xcode", "tradeoff": "Apple builds and distribution need macOS/Xcode; Android needs its own client.", "research_file": "native-mobile.json", "reviewed": "2026-10-10", "best_practices": [ "Keep presentation state small and actor-isolated; inject service and API boundaries for tests.", "Use structured concurrency with cancellation and store credentials in Keychain.", "Treat offline storage and synchronization as separate decisions, with explicit conflict handling.", "Check Dynamic Type, VoiceOver and real-device behavior; a simulator pass does not establish background or distribution behavior." ], "research_freshness": { "core_guidance_checked_on": "2026-10-13", "sources": [ "https://developer.apple.com/documentation/swiftui", "https://developer.apple.com/tutorials/data/documentation/swiftui.json" ], "scope": "Core framework roles, current setup/agent documentation and cited-source availability rechecked; not a reimplementation or exhaustive semantic audit of every third-party dependency." }, "guide_url": "/stacks/swift-swiftui-ios/", "markdown_url": "/stacks/swift-swiftui-ios/guide.md", "json_url": "/stacks/swift-swiftui-ios/record.json", "architecture_and_migration": { "id": "swift-swiftui-ios", "version_scope": "Documentation reviewed 11 October 2026. SwiftUI Observation and SwiftData are iOS/iPadOS 17+; support older OS targets through compatible alternatives. Pin Xcode/SDK/Swift/package resolution and retain the minimum OS/device matrix. No simulator, archive or store-release check was executed.", "operating_model": "An installed iOS client persists across backend releases and is suspended or terminated under OS control. Recommendation: SwiftUI views render observable presentation state while repositories own URLSession DTOs and local persistence. Store rollout, API compatibility and local-store migration are separate adoption gates.", "architecture": [ "Use SwiftUI state/Observation according to minimum OS availability; keep view rendering separate from asynchronous repositories and business decisions. Observation is UI dependency tracking, not disk persistence.", "Recommendation: version API DTOs separately from SwiftData/Core Data entities; preserve old installed-client contracts and authorize all privileged operations on the backend.", "Use a versioned local schema and reviewed migration plan for SwiftData. Recommendation: store unacknowledged user intents durably before claiming an offline write succeeded; reconcile conflicts with an explicit server policy.", "Separate foreground structured concurrency, OS-scheduled refresh/processing, background URLSession transfers and server durable jobs. Each has different completion and cancellation semantics.", "Recommendation: Keychain stores credential material; isolate account-local data and clear/lock the appropriate state on account switch. Keep backend provider secrets out of the app bundle." ], "developer_workflow": [ "Start in the external Xcode source checkout. Read README, minimum OS, shared scheme, signing owner, capabilities, API fixtures and every persisted schema version.", "Record xcodebuild -version and xcode-select -p; use xcodebuild -list -project App.xcodeproj and xcodebuild -showdestinations -project App.xcodeproj -scheme App with the actual names. Resolve packages with xcodebuild -resolvePackageDependencies -project App.xcodeproj -scheme App. Check current flags with the pinned xcodebuild -help; the linked command-line FAQ is archived.", "After choosing an installed simulator UUID, run xcodebuild test -project App.xcodeproj -scheme App -destination 'platform=iOS Simulator,id=' -resultBundlePath .xcresult. Placeholders require substitution; simulator results do not establish device background behavior.", "Recommendation: use Instruments/network diagnostics, physical-device background checks, upgrade fixtures, VoiceOver and large text. Produce a signed archive/TestFlight update under the established release workflow; record exact old/new client builds and compatible backend revisions." ], "avoid": [ "Assuming users update when the backend deploys strands old installed clients and offline requests.", "Assuming an older executable can read a migrated store confuses binary rollback with data rollback.", "Keeping pending offline writes only in view state loses work after suspension or termination.", "Using BGAppRefreshTask as an exact timer or unlimited durable worker ignores OS scheduling and expiration.", "Using phased release as install reversal overlooks manual downloads and devices already running the new version." ], "transitions": [ { "capability": "client", "existing_contract": "Installed versions, minimum OS, URLSession DTOs/errors, deep links, auth expiry and old/offline writes.", "coexistence": "Recommendation: Ship additive backend responses and versioned fixtures before the new client; retain old contracts until measured adoption and an explicit support policy permit retirement.", "target": "Recommendation: Separate API DTOs from local models and use capability negotiation for optional features; authorization remains backend-owned.", "benefits": [ { "benefit": "Independent backend/client deployment can preserve supported installations.", "prerequisites": "Inventory of real installed versions, API fixtures and release/support owners.", "tradeoffs": "Long-lived version support costs maintenance; a new store release cannot force immediate adoption." } ], "checks": [ "Old and new builds run against the same new backend.", "Unknown optional fields and absent new fields do not break supported clients.", "A delayed old-client mutation receives the documented success/conflict/upgrade response." ], "rollback": "Disable the new server feature and retain both API contracts; already-installed clients require a compatible forward fix when needed.", "sources": [ "https://developer.apple.com/documentation/foundation/urlsession", "https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases/" ], "id": "client-1" }, { "capability": "data", "existing_contract": "Existing on-device store versions, entity meaning, relationships, pending local writes and upgrade paths.", "coexistence": "Recommendation: Add compatible fields/stages before removing representations; migration fixtures include every supported historical store and unacknowledged operations.", "target": "Recommendation: Use SwiftData VersionedSchema and SchemaMigrationPlan when OS support permits; preserve the established Core Data/store choice if migration value is unproven.", "benefits": [ { "benefit": "An explicit schema history makes upgrade behavior inspectable.", "prerequisites": "Reviewed stages and fixtures proving values/relationships/pending writes survive.", "tradeoffs": "Forward migration does not establish older-binary readability; cross-store conversion is application work." } ], "checks": [ "Open each supported old store with the new build and compare user data and pending operations.", "Interrupt migration and verify recovery behavior.", "Attempt the intended rollback build against the migrated fixture; reject release rollback if unreadable." ], "rollback": "Prefer a compatible forward repair if downgrade is unqualified. Restore a pre-upgrade copy only under a reconciled policy that does not erase later local writes.", "sources": [ "https://developer.apple.com/documentation/swiftdata/schemamigrationplan", "https://developer.apple.com/documentation/swiftdata/versionedschema" ], "id": "data-1" }, { "capability": "cache", "existing_contract": "Local reads, pending offline changes, tombstones/cursors and server conflict semantics.", "coexistence": "Recommendation: Keep the server as shared-domain reconciler; record each local mutation durably with a stable operation ID and schema version while old clients use the same conflict policy.", "target": "Recommendation: Use repository-owned local reads and a persistent operation log when offline writes are required; choose revision checks, merge or user resolution per domain instead of accidental timestamp wins.", "benefits": [ { "benefit": "Users can retain local work through intermittent connectivity.", "prerequisites": "Durable local storage, replay-safe backend, explicit conflict/tombstone protocol.", "tradeoffs": "This is a proposed application design; SwiftData does not automatically provide arbitrary backend synchronization." } ], "checks": [ "Two devices edit the same record offline; the declared policy preserves or exposes both intents.", "Disconnect after server commit but before acknowledgement; replay does not duplicate the effect.", "Restart/sign-out does not silently replay account A operations as account B." ], "rollback": "Stop the new synchronizer, retain pending operations and translate/reconcile them before returning to old logic; never clear the log as a rollback shortcut.", "sources": [ "https://developer.apple.com/documentation/swiftdata/schemamigrationplan", "https://developer.apple.com/documentation/foundation/urlsession" ], "id": "cache-1" }, { "capability": "jobs", "existing_contract": "Foreground task cancellation, pending intents and any existing background task identifiers/handlers.", "coexistence": "Recommendation: Retain old handler identifiers and persisted payload readers while new code is installed; use one owner per sync operation.", "target": "Recommendation: Choose BGAppRefreshTask/BGProcessingTask for eligible opportunistic device work, foreground tasks for interactive work and backend durable jobs for server completion obligations.", "benefits": [ { "benefit": "Eligible refresh/maintenance can execute while the app is backgrounded.", "prerequisites": "Capabilities, registered handlers, durable checkpoints and expiration handling.", "tradeoffs": "The OS selects launch time; device scheduling does not satisfy a fixed backend completion SLA." } ], "checks": [ "Expire a task midway; it checkpoints/cancels and marks completion correctly.", "Suspend/terminate/relaunch and resume without a duplicated business effect.", "Offline, battery and permission constraints show honest pending state." ], "rollback": "Disable new task submission while preserving payload readers/handlers long enough to reconcile pending work; continue foreground sync or a server job where appropriate.", "sources": [ "https://developer.apple.com/documentation/backgroundtasks", "https://developer.apple.com/documentation/backgroundtasks/choosing-background-strategies-for-your-app" ], "id": "jobs-1" }, { "capability": "files", "existing_contract": "Existing upload/download IDs, authorized object keys, file hashes, task identifiers and completion acknowledgements.", "coexistence": "Recommendation: Keep server upload endpoints/object ownership compatible; persist mapping from background task to logical operation and retain file-backed upload payloads.", "target": "Recommendation: Use an identified background URLSession for eligible HTTP(S) transfer; recreate it after system termination and move completed temporary downloads before delegate return.", "benefits": [ { "benefit": "Transfers can continue during suspension without holding the app process.", "prerequisites": "Delegate lifecycle, stable session identifier, protected files and authorized retry/acknowledgement contract.", "tradeoffs": "Background uploads require files; scheduling is not exact and transfer completion differs from domain acceptance." } ], "checks": [ "Suspend during upload/download and restore the same session after system termination.", "Verify file integrity and durable location after completion.", "Retry an ambiguous response without producing duplicate owned objects." ], "rollback": "Stop creating new transfers, inspect/cancel or finish existing tasks and reconcile server objects; keep session callbacks until all retained tasks are accounted for.", "sources": [ "https://developer.apple.com/documentation/foundation/downloading-files-in-the-background" ], "id": "files-1" }, { "capability": "operations", "existing_contract": "Store release ownership, supported devices, adoption, crash reports and persisted-data compatibility.", "coexistence": "Recommendation: Verify TestFlight install-over-existing fixtures; retain server compatibility through phased adoption and include manual downloads in risk assessment.", "target": "Recommendation: Use phased release with explicit crash/data-loss/compatibility stop criteria; assess adoption before retiring old API behavior.", "benefits": [ { "benefit": "Gradual automatic-update distribution can limit initial exposure.", "prerequisites": "Signed reviewed build, live telemetry and a compatible recovery release.", "tradeoffs": "Apple's seven-day phases cover eligible automatic updates; anyone can manually download, and pausing does not reverse installs." } ], "checks": [ "Verify real install/update preserves store, credentials and deep links.", "Track old/new build support and migration failures separately.", "Pause/recovery procedure leaves already-updated clients functional." ], "rollback": "Pause further distribution and disable affected server capabilities if safe; ship a compatible repair rather than assuming an installed-version/store downgrade.", "sources": [ "https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases/" ], "id": "operations-1" } ], "sources": [ { "url": "https://developer.apple.com/documentation/swiftui/managing-model-data-in-your-app", "title": "SwiftUI Managing Model Data", "claim": "Observation connects model changes to UI and requires iOS/iPadOS 17+; it is not local persistence." }, { "url": "https://developer.apple.com/documentation/swiftdata/schemamigrationplan", "title": "SwiftData SchemaMigrationPlan", "claim": "Versioned schemas and migration stages explicitly model local schema evolution; iOS/iPadOS 17+." }, { "url": "https://developer.apple.com/documentation/swiftdata/versionedschema", "title": "SwiftData VersionedSchema", "claim": "A schema records a particular version and its model set." }, { "url": "https://developer.apple.com/documentation/foundation/urlsession", "title": "Foundation URLSession", "claim": "Configured sessions own data/upload/download/WebSocket tasks, authentication callbacks and asynchronous transfer behavior." }, { "url": "https://developer.apple.com/documentation/backgroundtasks", "title": "Background Tasks", "claim": "Register and schedule task handlers for eligible background processing; the framework has multiple task types." }, { "url": "https://developer.apple.com/documentation/backgroundtasks/choosing-background-strategies-for-your-app", "title": "Choosing Background Strategies", "claim": "Select task strategy by workload, handle expiration and completion; the OS decides refresh/processing launch time." }, { "url": "https://developer.apple.com/documentation/foundation/downloading-files-in-the-background", "title": "Downloading Files in the Background", "claim": "Background sessions require delegates/stable identifiers, support file-backed uploads and need completion-file lifecycle handling." }, { "url": "https://developer.apple.com/documentation/security/keychain-services", "title": "Keychain Services", "claim": "Encrypted Keychain items can store small credential secrets." }, { "url": "https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases/", "title": "App Store Connect Phased Release", "claim": "Automatic updates progress over seven days; manual downloads remain possible and phases can be paused." }, { "url": "https://developer.apple.com/documentation/xcode/testing", "title": "Xcode Testing", "claim": "Swift Testing and XCTest/UI tests have complementary roles; testing is separate from distribution." }, { "url": "https://developer.apple.com/library/archive/technotes/tn2339/_index.html", "title": "Archived Xcode Command-line FAQ", "claim": "Documents command shapes for scheme/project/destination tests and archives; recheck options with the pinned Xcode toolchain." } ], "reviewed_at": "2026-10-11", "evidence": "documentation-reviewed" }, "rewrite_url": "/rewrite/guide.md", "migration_contracts_url": "/rewrite/contracts.json", "agent_workflow": [ "Read README, dependency manifests, lockfiles, runtime pins and the maintained project workflow before changing anything. Preserve an existing stack unless reconsidering it is part of the request.", "Use this guide to select tools by requirement. Resolve compatible versions from official and installed-version documentation; record the actual lockfile and runtime versions.", "Create a plan for schema changes, identity, authorization, external effects and deployment. A library choice does not complete its integration.", "Run relevant checks after configuration. Exercise the real interface, failure paths and packaged artifact on the intended target. Report commands, versions, results and untested behavior.", "On failure, retain the command and diagnostic, fix the failing prerequisite and resume there. Do not regenerate over existing work or suppress failures to make a check green." ], "selection": { "native_ui": true, "static_hosting": false, "offline_client_candidate": true }, "coverage_note": "Tools are curated starting points for this application role. Exact versions, integrations and offline behavior require project-specific qualification." }