Native Mobile App (iOS/Android) Rules for Windsurf

# Native Mobile App (iOS/Android) Rules for Windsurf

# Native Mobile App Development Rules

## Offline-First Architecture
- Assume no network — design for offline from day 1
- Local-first data model: write to local DB, sync to server in background
- Conflict resolution strategy before you need it (last-write-wins or CRDTs)
- Clear offline indicators in UI — never pretend to be online when not
- Sync queue: operations queue up when offline, execute when connected

## App State Management
- Single source of truth for app state
- iOS: @Observable + SwiftData or Core Data
- Android: ViewModel + StateFlow + Room
- Persist UI state through process death — users lose patience with resets
- Background refresh: use BackgroundTasks (iOS) or WorkManager (Android)

## Performance
- List performance: DiffableDataSource (iOS) / DiffUtil (Android) for smooth scrolling
- Image loading: lazy, with caching, at correct size — never load 4K images in a thumbnail
- Memory warnings: respond to them (iOS: applicationDidReceiveMemoryWarning)
- Main thread only for UI — all network/DB on background queues
- Profile with Instruments (iOS) or Android Profiler before shipping

## Networking
- Certificate pinning for financial/sensitive apps
- Retry with exponential backoff for transient failures
- Request cancellation when user leaves screen — don't update unmounted view
- Response caching with appropriate Cache-Control headers
- Never expose API keys in client code — use device attestation + backend

## Push Notifications
- Request permission at the right moment — contextual, not on first launch
- Local notifications for time-sensitive local events
- Remote notifications: small payload + fetch content in background
- Deep linking from notifications: every notification should land somewhere specific
- Notification analytics: delivered, opened, dismissed rates

## App Store / Play Store