/port

Native Architecture Mapping (MAP phase)

Translate the web architecture surfaced in web-analysis-checklist.md into two separate native architectures — one for iOS, one for Android. The mapping is per-screen and per-feature. Never produce a single unified spec.

Default Architectures

iOS — SwiftUI + MVVM-C

[ App ]
  └─ Composition Root (DI container)
      ├─ Coordinator(s)            ← navigation
      │    ├─ Tab / Stack / Sheet drivers
      │    └─ Deep-link router
      ├─ Feature Modules
      │    ├─ View (SwiftUI)
      │    ├─ ViewModel (@Observable, async/await)
      │    ├─ UseCase (pure async functions)
      │    └─ Repository (protocol + impl)
      ├─ Services
      │    ├─ APIClient (URLSession + async/await)
      │    ├─ AuthService (ASWebAuthenticationSession + Keychain)
      │    ├─ Storage (SwiftData / Core Data / FileManager)
      │    └─ Push, Analytics, Logger, FeatureFlags
      └─ Design System (Tokens, Components)

Why MVVM-C:

• SwiftUI is declarative; the View needs a thin observable VM that drives state.
• Coordinators centralize navigation so deep links, programmatic flows, and modal sheets stay testable.
• @Observable (Swift 5.9+) replaces ObservableObject boilerplate; pair with @Bindable in the View.

Android — Jetpack Compose + MVVM (or MVI for high-state-complexity screens)

[ App ]
  └─ Application + DI (Hilt)
      ├─ NavHost (Navigation Compose, type-safe routes)
      │    └─ Deep-link handler (App Links)
      ├─ Feature Modules
      │    ├─ Screen Composable (UiState in, events out)
      │    ├─ ViewModel (StateFlow<UiState>)
      │    ├─ UseCase (suspend / Flow)
      │    └─ Repository (interface + impl)
      ├─ Services
      │    ├─ Network (Ktor or Retrofit + OkHttp)
      │    ├─ Auth (AppAuth + Custom Tabs + EncryptedSharedPreferences)
      │    ├─ Storage (Room + DataStore)
      │    └─ Push, Analytics, Logger, FeatureFlags
      └─ Design System (Material 3 theme, Tokens, Components)

Why MVVM with single UiState:

• Compose recomposes on state change; a single StateFlow<UiState> per screen avoids torn renders.
• MVI is justified when a screen has many discrete intents (e.g., complex forms, real-time editor) — use a Reducer<UiState, Intent> pattern.

Per-Screen Mapping Template

For every web route, produce one row of this table. Treat the table as the canonical handoff to Native.

Divergence is fine. Document it. The web app's IA is not the source of truth — platform conventions are.

Navigation Translation

Anti-pattern: Mapping a 5-level web breadcrumb directly to a 5-deep stack. Re-conceive as 1-2 levels max with content denormalization.

State Management Translation

Critical: Do not port a 30-slice Redux store as one giant AppState. Decompose into feature ViewModels. Cross-cutting state (current user, theme, network) belongs in a small shared AppState.

Data Fetching Translation

Cache invalidation: model your repository tiers explicitly — memory → disk → network with TTLs. Web react-query defaults (5 min stale time) are reasonable starting values.

Module Decomposition

iOS (Swift Package Manager)

Packages/
  AppCore/              ← cross-cutting: networking, auth, design tokens, logger
  Features/
    Home/               ← View + VM + UseCase + Repository
    ProductDetail/
    Cart/
    Checkout/
    Account/
  DesignSystem/         ← tokens, components, icons
App/
  iOSApp/               ← composition root, AppDelegate, entitlements

Android (Gradle multi-module)

:app                    ← composition root, manifest, DI graph
:core
  :core:network
  :core:auth
  :core:database
  :core:designsystem
  :core:common
:feature
  :feature:home
  :feature:productdetail
  :feature:cart
  :feature:checkout
  :feature:account

Mirror the web feature folders only when they map cleanly. If the web app is organized by route and the natural mobile organization is by feature domain, regroup. Architecture mapping is a re-conception, not a copy.

Concurrency Model

Swift 6 strict concurrency is the default. Swift 6.2 + Xcode 26 ship Approachable Concurrency (SWIFT_APPROACHABLE_CONCURRENCY=YES): new projects default to MainActor isolation for all code and NonisolatedNonsendingByDefault lets nonisolated async functions inherit the caller's isolation — fewer Sendable boundary errors. Opt into background execution with @concurrent / explicit nonisolated. Annotate boundaries with @MainActor or Sendable correctly; do not silence concurrency warnings.

Kotlin 2.2.20 + K2 is the 2026 baseline. JetBrains' coming Swift export work for KMP coroutines + flows is in active development; track for downstream impact on iOS interop.

Dependency Injection

OS Baseline Decision

Pick a baseline at MAP phase, justify it from the survey (especially if web analytics show a long-tail of older devices), and document.

MAP Output Skeleton

# Native Architecture Map: <App Name>

## iOS Architecture
- Pattern: SwiftUI + MVVM-C
- Min iOS: 16
- DI: …
- Module layout: …

## Android Architecture
- Pattern: Compose + MVVM (or MVI per screen)
- Min API: 28
- DI: Hilt
- Module layout: …

## Per-screen mapping
| Web route | iOS | Android | Notes |
| …         | …   | …       | …     |

## Navigation translation
- Tabs: …
- Modals: …
- Deep links: …

## State translation
- Global → per-feature VMs: …
- AppState (cross-cut): …
- Form state: …

## Data fetching
- iOS client: …
- Android client: …
- Cache tiers: memory / disk / network

## Concurrency
- iOS: Swift 6 strict
- Android: Coroutines + Flow

## OS baseline rationale
- iOS NN because …
- API NN because …

This map feeds BLUEPRINT and HANDOFF.