Apple Platform Engineering
Comprehensive Swift engineering standards for building production-quality Apple platform applications.
Core Principles
- No Force Unwrapping (
!) - Useguard let,if let, nil coalescing (??), or optional chaining. Never crash on nil. - Actor-First Concurrency - Use actors as the default for stateful components. Prefer actor isolation over manual locking.
- Async/Await Always - Never use completion handlers in new code. Use
async throwsfunctions. - Sendable Everything - All shared types must conform to
Sendable. All closures crossing concurrency boundaries must be@Sendable. - Swift 6 Strict Concurrency - Enable
StrictConcurrencyfrom the start. No data races. - Protocol-Oriented Design - Define contracts through protocols. Use dependency injection for testability.
- LocalizedError for Errors - Domain-specific error enums conforming to
LocalizedError, Sendable.
Quick Reference
Safe Optional Handling
| Instead of | Use |
|---|---|
value! | guard let value else { return } |
string.data(using: .utf8)! | string.data(using: .utf8) ?? Data() |
url! | guard let url = URL(string: s) else { return } |
object.property! | object.property?.method() or if let prop = object.property { } |
Concurrency Primitives
| Need | Use |
|---|---|
| Stateful shared component | actor |
| Simple value protection | Mutex<State> |
| Low-level sync | OSAllocatedUnfairLock |
| UI state management | @MainActor on ViewModels |
| Progress/events stream | AsyncStream / AsyncThrowingStream |
| Multi-subscriber broadcast | AsyncBroadcastChannel or AsyncNotifier |
Actor vs @MainActor Decision
| Scenario | Use |
|---|---|
| API service, data operations | actor |
ViewModel with @Published | @MainActor final class: ObservableObject |
Service with @Published properties Views observe | @MainActor ObservableObject (rare) |
| Pure data model | struct: Sendable |
Error Handling Pattern
enum ServiceError: LocalizedError, Sendable {
case operationFailed(String)
var errorDescription: String? {
switch self {
case .operationFailed(let msg): return "Operation failed: \(msg)"
}
}
}
API Design
| Pattern | Use |
|---|---|
func work() async throws -> T | Standard async operation |
func work() -> AsyncThrowingStream<Event, Error> | Progress/event reporting |
func work(progress: @Sendable (Float) -> Void) async throws -> T | Simple progress callback |
Metal GPU Quick Reference
| Need | Use |
|---|---|
| Compute pipeline | MTLComputePipelineDescriptor + device.makeComputePipelineState |
| Render pipeline | MTLRenderPipelineDescriptor + vertex/fragment functions |
| Buffer management | MetalBuffer<Element> generic wrapper |
| Multi-frame pipelining | Ring buffer (pool of 3) with tick() |
| Texture from IOSurface | device.makeTexture(descriptor:iosurface:plane:) |
| Threadgroup sizing | min(elementCount, pipelineState.maxTotalThreadsPerThreadgroup) |
RealityKit/visionOS Quick Reference
| Need | Use |
|---|---|
| Custom entity data | struct: Component |
| Per-frame logic | class: System with scene subscriptions |
| Show entities in SwiftUI | RealityView { content in content.add(entity) } |
| Observe component changes | entity.componentChangePublisher(T.self) |
| Full immersion | ImmersiveSpace(id:) { }.immersionStyle(.full) |
| Multi-window | WindowGroup(id:) with WindowPlacement |
Advanced Patterns Quick Reference
| Need | Use |
|---|---|
| Smooth value tracking | ExponentialDamper<T: Lerpable> |
| Generic interpolation | Lerpable protocol with lerp(from:to:blend:) |
| Non-empty guarantee | NonEmpty<C: Collection> |
| Enum-keyed storage | Table<E: CaseIterable, V> |
| Multi-consumer async | AsyncBroadcastChannel with back-pressure |
| Combine to async | publisher.sinkSingleValue() async throws |
| Custom defaults | @DefaultValue<T> property wrapper |
Detailed References
- swift-concurrency.md — Swift 6 concurrency patterns: actors, Sendable, AsyncSequence, task cancellation, synchronization, state machines, reactive patterns, generics, persistence, networking, testing, diagnostics
- swiftui-architecture.md — SwiftUI app architecture: MVVM, ViewModel/View guidelines, service layer patterns, data flow, App Intents, file organization
- metal-graphics.md — Metal GPU programming: pipelines, buffers, textures, compute dispatch, ring buffers, shaders, frame pacing
- realitykit-visionos.md — RealityKit ECS and visionOS: entities, components, systems, scene subscriptions, immersive spaces, windows, hand tracking
- advanced-swift-patterns.md — Property wrappers, interpolation/animation, collection types, Combine bridging, advanced async abstractions, @dynamicMemberLookup