`ios/README.md`

44 lines
# iOS app (SwiftUI) — module map

The native client is **not** scaffolded yet (needs Xcode + an Apple Developer
account + the Tesla app registration). This is the target module layout so the
backend contract and the recommendation core stay aligned with the client.

Build with SwiftUI + Swift Concurrency (async/await, actors). Combine only for
long-lived publisher streams. The app calls **only** the first-party backend —
no provider secrets in the binary.

## Feature / infrastructure modules

| Module | Responsibility |
|---|---|
| `AppShell` | Auth state, tab navigation, deep links, feature flags |
| `ExploreFeature` | Map, nearby search, station list, filters |
| `TripPlannerFeature` | Origin/destination, vehicle profile, route candidates |
| `StationDetailFeature` | Charger facts, provenance, walking map, amenities |
| `ActiveStopFeature` | Charging estimate, itinerary, timer, return alert |
| `TeslaConnectionFeature` | OAuth handoff, connection state, consent controls |
| `OfflineStore` | Cached corridor, stations, places, route, pending reports (GRDB) |
| `ProviderClient` | First-party backend API only — no provider secrets |
| `PrivacyCenter` | Export, history controls, disconnect, deletion |
| `Diagnostics` | Redacted logs, performance traces, crash reporting |

## Frameworks

Apple-first: SwiftUI, MapKit, Core Location, AuthenticationServices, URLSession,
Keychain, UserNotifications. Third-party (pinned via SPM, license + privacy
manifest reviewed): GRDB.swift (offline SQLite), Nuke (licensed image loading),
Sentry Cocoa (crash/perf, PII-scrubbed), XCTest/XCUITest, Fastlane.

## Shared contract

The Swift value types must mirror `backend/src/core/types.ts` and the estimator /
stop-score / activity-match logic so both sides agree. The recommendation math
lives server-side (`backend/src/core/`); the app renders results + confidence and
runs the local conservative timer when telemetry is unavailable.

## Deferred

CarPlay, Live Activities, Apple Watch companion, vehicle commands, virtual-key
pairing — all post-launch (see `../PLAN.md`).