Document Metadata

• title: iOS Architecture
• description: Current client-side structure and near-term design direction
• status: evolving
• lastUpdated: "2026-05-02 12:14 ET (America/New_York)"
• owner: Engineering

iOS Architecture ## Current Shape - MaintainApp creates the SwiftData model container - AppRootView switches across lo

iOS Architecture

Current Shape

• MaintainApp creates the SwiftData model container
• AppRootView switches across loading, runtime-configuration issue, sign-in, onboarding, and main-tab states
• AppModel is the central observable store for auth, local CRUD, HealthKit import, export manifests, and remote sync orchestration
• Feature views consume AppModel state instead of owning their own networking or persistence seams
• Real profile creation no longer seeds sample support data; sample-rich states are limited to repo-owned UI-testing and visual-checkpoint fixtures
• Runtime configuration validation now surfaces explicit packaged-config failures instead of silently collapsing into misleading local-only behavior

Key App Building Blocks

• ios/Sources/App/ for entry points
• ios/Sources/Features/ for screen-level features
• ios/Sources/Core/Models/ for domain and persistence models
• ios/Sources/Core/Services/ for HealthKit, insight generation, and remote sync seams
• ios/Sources/Core/DesignSystem/ and ios/Sources/Core/Components/ for UI consistency

Near-term Direction

• Keep local-first UX while tightening the current AppModel seams around sync, auth refresh, and HealthKit import
• Extract narrower coordinators from AppModel as the next hardening step instead of pushing more responsibility into the monolith
• Continue refining the maintenance-loop product language without expanding into unsupported clinical guidance

Provenance

• Source file: DOCS/development/ios-architecture.md
• Source URL: https://github.com/maggielerman/maintain-ios/blob/main/DOCS/development/ios-architecture.md