@zigrivers/scaffold 3.7.0 → 3.9.0

package/content/knowledge/mobile-app/mobile-app-observability.md

@@ -0,0 +1,317 @@
+---
+name: mobile-app-observability
+description: Crash reporting (Crashlytics/Sentry), analytics, performance monitoring, network tracing, and structured logging for mobile apps
+topics: [mobile-app, observability, crashlytics, sentry, analytics, performance-monitoring, network-tracing, logging]
+---
+
+Mobile observability is harder than server observability: you cannot SSH into a user's phone, crashes happen on thousands of device/OS combinations you cannot reproduce locally, and performance issues manifest differently across network conditions and hardware tiers. The goal is to know about problems before users report them, understand why they occurred, and have enough context to reproduce and fix them.
+
+## Summary
+
+Mobile observability requires crash reporting (Crashlytics or Sentry), structured analytics for user behavior and funnel tracking, real-user performance monitoring (launch time, screen transitions, network requests), and structured logging that survives app termination. Crashlytics and Sentry both capture symbolicated stack traces — symbolication requires uploading dSYMs (iOS) or mapping files (Android) in CI. Analytics events must be defined in a taxonomy before implementation. Performance monitoring should cover app start time, screen render time, and API latency percentiles.
+
+## Deep Guidance
+
+### Crash Reporting
+
+**Firebase Crashlytics setup**
+
+iOS (SPM):
+```swift
+// AppDelegate
+import FirebaseCrashlytics
+import FirebaseCore
+
+func application(_ application: UIApplication, didFinishLaunchingWithOptions...) -> Bool {
+    FirebaseApp.configure()
+    return true
+}
+```
+
+Android (Gradle):
+```kotlin
+// app/build.gradle.kts
+plugins {
+    id("com.google.firebase.crashlytics")
+}
+dependencies {
+    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))
+    implementation("com.google.firebase:firebase-crashlytics")
+}
+```
+
+**dSYM upload (iOS)**
+Without dSYMs, crash reports show memory addresses, not function names. Crashlytics auto-uploads dSYMs when the Crashlytics build phase is configured:
+
+```bash
+# Xcode build phase: Run Script
+"${PODS_ROOT}/FirebaseCrashlytics/run"
+```
+
+For Bitcode-disabled builds (Xcode 14+ default), dSYMs are generated at build time and uploaded automatically if the build phase is present. For CI builds:
+```bash
+# Upload dSYMs manually after archiving
+./Pods/FirebaseCrashlytics/upload-symbols -gsp GoogleService-Info.plist -p ios path/to/dSYMs
+```
+
+**Mapping file upload (Android)**
+```kotlin
+// app/build.gradle.kts
+buildTypes {
+    release {
+        firebaseCrashlytics {
+            mappingFileUploadEnabled = true  // uploads R8/ProGuard mapping file automatically
+            nativeSymbolUploadEnabled = true  // for NDK crash symbolication
+        }
+    }
+}
+```
+
+**Enriching crash reports**
+```swift
+// iOS: Add user context and breadcrumbs
+Crashlytics.crashlytics().setUserID(userId)
+Crashlytics.crashlytics().setCustomValue("premium", forKey: "subscription_tier")
+
+// Record non-fatal errors
+Crashlytics.crashlytics().record(error: networkError)
+
+// Add breadcrumb before risky operation
+Crashlytics.crashlytics().log("Attempting payment with method: \(paymentMethod)")
+```
+
+```kotlin
+// Android
+FirebaseCrashlytics.getInstance().setUserId(userId)
+FirebaseCrashlytics.getInstance().setCustomKey("subscription_tier", "premium")
+FirebaseCrashlytics.getInstance().recordException(exception)
+FirebaseCrashlytics.getInstance().log("Cart checkout started: items=${cartItems.size}")
+```
+
+**Sentry as alternative**
+Sentry provides richer error grouping, performance tracing in the same SDK, and self-hosting options:
+
+```swift
+// iOS
+import Sentry
+SentrySDK.start { options in
+    options.dsn = "https://key@sentry.io/project"
+    options.tracesSampleRate = 0.2      // 20% of sessions traced
+    options.profilesSampleRate = 0.1    // 10% of transactions profiled
+    options.enableCrashHandler = true
+}
+```
+
+```kotlin
+// Android
+SentryAndroid.init(context) { options ->
+    options.dsn = "https://key@sentry.io/project"
+    options.tracesSampleRate = 0.2
+    options.isEnableAutoActivityLifecycleBreadcrumbs = true
+}
+```
+
+### Analytics
+
+**Event taxonomy design**
+Define events before implementation. Use a consistent naming convention and document in a schema registry:
+
+```
+Event naming: {object}_{action}
+Examples:
+  user_signed_up
+  user_signed_in
+  product_viewed
+  product_added_to_cart
+  cart_checkout_started
+  order_placed
+  order_cancelled
+```
+
+Event properties follow snake_case:
+```
+product_viewed:
+  product_id: string
+  product_name: string
+  category: string
+  price_cents: int
+  position_in_list: int   # for recommendation tracking
+  source: string          # "search" | "recommendation" | "category_browse"
+```
+
+**Firebase Analytics (iOS)**
+```swift
+import FirebaseAnalytics
+
+Analytics.logEvent("product_viewed", parameters: [
+    "product_id": productId,
+    "product_name": productName,
+    "price_cents": priceCents,
+    "source": source
+])
+
+// User properties (persistent, applied to all subsequent events)
+Analytics.setUserProperty("premium", forName: "subscription_tier")
+```
+
+**Firebase Analytics (Android)**
+```kotlin
+firebaseAnalytics.logEvent("product_viewed") {
+    param("product_id", productId)
+    param("product_name", productName)
+    param("price_cents", priceCents.toLong())
+    param("source", source)
+}
+
+firebaseAnalytics.setUserProperty("subscription_tier", "premium")
+```
+
+**Analytics abstraction layer**
+Never call analytics SDKs directly from feature code — use an abstraction:
+
+```swift
+protocol AnalyticsService {
+    func track(_ event: AnalyticsEvent)
+    func setUserProperty(_ value: String, for key: String)
+}
+
+enum AnalyticsEvent {
+    case productViewed(productId: String, name: String, priceCents: Int, source: String)
+    case orderPlaced(orderId: String, itemCount: Int, totalCents: Int)
+}
+
+final class FirebaseAnalyticsService: AnalyticsService {
+    func track(_ event: AnalyticsEvent) {
+        switch event {
+        case .productViewed(let id, let name, let price, let source):
+            Analytics.logEvent("product_viewed", parameters: [
+                "product_id": id, "product_name": name,
+                "price_cents": price, "source": source
+            ])
+        case .orderPlaced(let id, let count, let total):
+            Analytics.logEvent("order_placed", parameters: [
+                "order_id": id, "item_count": count, "total_cents": total
+            ])
+        }
+    }
+}
+```
+
+This allows swapping analytics providers, testing with a mock, and preventing typos in event names.
+
+### Performance Monitoring
+
+**App startup time (iOS)**
+```swift
+// Measure time from app launch to first interactive frame
+// FirebasePerformance trace
+let trace = Performance.startTrace(name: "app_startup")
+// ... app initialization ...
+trace?.stop()
+```
+
+Instruments > App Launch template records the full cold start time with a flame graph of initialization cost. Target: under 400ms pre-main time (Swift static initializers, ObjC +load methods).
+
+**App startup time (Android)**
+```kotlin
+// Firebase Performance: automatic activity launch monitoring
+// Manual trace for custom startup paths
+val trace = Firebase.performance.newTrace("app_cold_start")
+trace.start()
+// ... initialization ...
+trace.stop()
+```
+
+Systrace and Android Studio Profiler > CPU: record app startup to identify slow initialization. Common causes: synchronous disk I/O, large dependency injection graphs, synchronous network calls.
+
+**Network performance (Firebase Performance)**
+Firebase Performance automatically monitors HTTP requests made through URLSession (iOS) and OkHttp/HttpURLConnection (Android) without code changes.
+
+Manual HTTP tracing:
+```swift
+// iOS custom network trace
+let metric = HTTPMetric(url: url, httpMethod: .get)
+metric?.start()
+let (data, response) = try await URLSession.shared.data(from: url)
+metric?.responseCode = (response as? HTTPURLResponse)?.statusCode ?? -1
+metric?.stop()
+```
+
+```kotlin
+// Android: OkHttp interceptor for custom metrics
+class PerformanceInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request()
+        val metric = Firebase.performance.newHttpMetric(request.url.toString(), request.method)
+        metric.start()
+        val response = chain.proceed(request)
+        metric.setHttpResponseCode(response.code)
+        metric.stop()
+        return response
+    }
+}
+```
+
+**Screen render time**
+```swift
+// iOS: measure time to interactive per screen
+func measureScreenLoad(screenName: String) {
+    let trace = Performance.startTrace(name: "screen_\(screenName)_load")
+    // Stop trace when first meaningful paint is complete
+    DispatchQueue.main.asyncAfter(deadline: .now() + 0.1) {
+        trace?.stop()
+    }
+}
+```
+
+Set performance budget alerts in Firebase Performance: alert when p75 app start > 3s, p90 network response > 2s.
+
+### Structured Logging
+
+**iOS: os_log / OSLog framework**
+```swift
+import OSLog
+
+private let logger = Logger(subsystem: "com.example.myapp", category: "Checkout")
+
+func processOrder(_ order: Order) async throws {
+    logger.info("Order processing started: orderId=\(order.id, privacy: .public)")
+    do {
+        let result = try await paymentService.charge(order)
+        logger.info("Payment succeeded: orderId=\(order.id, privacy: .public) amount=\(order.totalCents)")
+    } catch {
+        logger.error("Payment failed: orderId=\(order.id, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        throw error
+    }
+}
+```
+
+Privacy annotations matter:
+- `privacy: .public`: logged in production — use for non-PII identifiers
+- `privacy: .private`: redacted in production (shown as `<private>`) — default for user data
+- `privacy: .sensitive`: always redacted — for credentials and PII
+
+**Android: structured logging with tags**
+```kotlin
+private const val TAG = "Checkout"
+
+fun processOrder(order: Order) {
+    Log.i(TAG, "Order processing started orderId=${order.id}")
+    try {
+        val result = paymentService.charge(order)
+        Log.i(TAG, "Payment succeeded orderId=${order.id} amount=${order.totalCents}")
+    } catch (e: Exception) {
+        Log.e(TAG, "Payment failed orderId=${order.id}", e)
+        throw e
+    }
+}
+```
+
+In production, always integrate with a crash reporter (Crashlytics, Sentry) — `android.util.Log` output is not captured in release builds without a custom log handler.
+
+**Log levels**
+- DEBUG: development-only context, not emitted in production builds
+- INFO: business events worth auditing (login, purchase, key feature usage)
+- WARNING: recoverable errors, degraded functionality
+- ERROR: failures that should be investigated (but app continues)
+- FATAL/CRITICAL: unrecoverable errors preceding a crash — rarely used directly

package/content/knowledge/mobile-app/mobile-app-offline-patterns.md

@@ -0,0 +1,311 @@
+---
+name: mobile-app-offline-patterns
+description: Local storage (SQLite/Room/Core Data), sync engines, conflict resolution, and background sync for offline-capable mobile apps
+topics: [mobile-app, offline, sqlite, room, core-data, sync, conflict-resolution, background-sync]
+---
+
+Offline capability is not optional for mobile apps — cellular networks are unreliable, users enter tunnels and basements, and users expect their data to persist between sessions. The complexity of offline architecture scales with sync complexity: read-only cache is trivial; bidirectional sync with conflict resolution is one of the hardest problems in software. Define your offline model explicitly before implementing persistence.
+
+## Summary
+
+Mobile offline patterns use local databases (Room+SQLite for Android, Core Data or GRDB for iOS) as the primary source of truth, with network sync as a background process. The "offline-first" pattern means the UI reads from local storage and writes to a local queue, which syncs independently. Conflict resolution strategies range from "last write wins" to CRDTs for complex cases. Background sync uses WorkManager (Android) or BGTaskScheduler (iOS) — not raw background threads.
+
+## Deep Guidance
+
+### Storage Layer Options
+
+**Android: Room (SQLite abstraction)**
+
+Room is the recommended local database for Android. It enforces compile-time query validation:
+
+```kotlin
+@Entity(tableName = "users")
+data class UserEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val email: String,
+    @ColumnInfo(name = "updated_at") val updatedAt: Long,
+    @ColumnInfo(name = "sync_status") val syncStatus: SyncStatus = SyncStatus.SYNCED
+)
+
+enum class SyncStatus { SYNCED, PENDING_CREATE, PENDING_UPDATE, PENDING_DELETE }
+
+@Dao
+interface UserDao {
+    @Query("SELECT * FROM users WHERE sync_status != 'PENDING_DELETE'")
+    fun observeUsers(): Flow<List<UserEntity>>
+
+    @Query("SELECT * FROM users WHERE sync_status != 'SYNCED'")
+    suspend fun getPendingSync(): List<UserEntity>
+
+    @Upsert
+    suspend fun upsert(user: UserEntity)
+
+    @Query("UPDATE users SET sync_status = :status WHERE id = :id")
+    suspend fun updateSyncStatus(id: String, status: SyncStatus)
+}
+
+@Database(entities = [UserEntity::class], version = 1, exportSchema = true)
+abstract class AppDatabase : RoomDatabase() {
+    abstract fun userDao(): UserDao
+}
+```
+
+Schema migrations: export schema with `exportSchema = true` (required for migration testing). Write explicit migrations:
+```kotlin
+val MIGRATION_1_2 = object : Migration(1, 2) {
+    override fun migrate(db: SupportSQLiteDatabase) {
+        db.execSQL("ALTER TABLE users ADD COLUMN avatar_url TEXT")
+    }
+}
+```
+
+**Android: DataStore for preferences**
+- `Preferences DataStore`: key-value pairs for simple settings (replaces SharedPreferences)
+- `Proto DataStore`: typed storage using Protocol Buffers for structured preferences
+- DataStore is coroutine-native; SharedPreferences is synchronous on the main thread — never use SharedPreferences for new code
+
+```kotlin
+val dataStore: DataStore<Preferences> = context.createDataStore(name = "settings")
+val USER_TOKEN = stringPreferencesKey("user_token")
+
+// Write
+dataStore.edit { settings -> settings[USER_TOKEN] = token }
+
+// Read
+val tokenFlow: Flow<String?> = dataStore.data.map { it[USER_TOKEN] }
+```
+
+**iOS: GRDB (SQLite wrapper)**
+
+GRDB provides a type-safe Swift SQLite interface with Combine/async integration:
+
+```swift
+struct User: Codable, FetchableRecord, PersistableRecord {
+    var id: String
+    var name: String
+    var email: String
+    var updatedAt: Date
+    var syncStatus: SyncStatus = .synced
+}
+
+// Write
+try dbQueue.write { db in
+    try user.save(db)  // INSERT OR REPLACE
+}
+
+// Observe changes
+let observation = ValueObservation.tracking { db in
+    try User.filter(Column("syncStatus") != SyncStatus.pendingDelete).fetchAll(db)
+}
+observation.start(in: dbQueue) { users in
+    // React to database changes
+}
+```
+
+**iOS: Core Data (Apple's ORM)**
+
+Core Data is the Apple-native persistence framework. It provides object graph management, lazy faulting, and iCloud sync (CloudKit integration):
+
+```swift
+// NSManagedObject subclass
+@objc(UserMO)
+class UserMO: NSManagedObject {
+    @NSManaged var id: String
+    @NSManaged var name: String
+    @NSManaged var syncStatus: Int16
+}
+
+// Fetch with NSFetchedResultsController for UI reactivity
+let request: NSFetchRequest<UserMO> = UserMO.fetchRequest()
+request.predicate = NSPredicate(format: "syncStatus != %d", SyncStatus.pendingDelete.rawValue)
+request.sortDescriptors = [NSSortDescriptor(keyPath: \UserMO.name, ascending: true)]
+
+let controller = NSFetchedResultsController(
+    fetchRequest: request,
+    managedObjectContext: viewContext,
+    sectionNameKeyPath: nil,
+    cacheName: nil
+)
+```
+
+Use a background `NSManagedObjectContext` for data imports — never import on the `viewContext` (main thread). Merge changes back to viewContext with `mergeChanges(fromContextDidSave:)`.
+
+**iOS: SwiftData (iOS 17+)**
+
+SwiftData is the modern replacement for Core Data with a Swift-native API:
+
+```swift
+@Model
+class User {
+    var id: String
+    var name: String
+    var email: String
+    var syncStatus: SyncStatus
+
+    init(id: String, name: String, email: String) {
+        self.id = id
+        self.name = name
+        self.email = email
+        self.syncStatus = .synced
+    }
+}
+
+// Query with SwiftUI
+@Query(filter: #Predicate<User> { $0.syncStatus != .pendingDelete })
+var users: [User]
+```
+
+SwiftData targets iOS 17+ — if supporting iOS 16, use GRDB or Core Data.
+
+### Offline-First Architecture
+
+**The offline-first pattern**
+The UI never calls the network directly. All writes go to the local database with a `PENDING` sync status. A background sync engine reads pending items and attempts to sync:
+
+```
+User Action → Write to Local DB (status: PENDING) → Notify UI
+                                    ↓
+                          Background Sync Engine
+                                    ↓
+                          POST/PATCH/DELETE to API
+                                    ↓
+                     Success: Update status to SYNCED
+                     Failure: Retry with exponential backoff
+```
+
+**Repository pattern for offline-first (Android)**
+```kotlin
+class UserRepository @Inject constructor(
+    private val userDao: UserDao,
+    private val userApi: UserApi,
+    private val syncQueue: SyncQueue
+) {
+    fun observeUsers(): Flow<List<User>> =
+        userDao.observeUsers().map { entities -> entities.map { it.toDomain() } }
+
+    suspend fun updateUser(user: User) {
+        // Write locally first — UI responds immediately
+        userDao.upsert(user.toEntity().copy(syncStatus = SyncStatus.PENDING_UPDATE))
+        // Enqueue sync (fires in background)
+        syncQueue.enqueue(SyncOperation.UpdateUser(user.id))
+    }
+}
+```
+
+**Sync queue implementation (Android: WorkManager)**
+```kotlin
+class SyncWorker(
+    context: Context,
+    params: WorkerParameters,
+    private val userRepository: UserRepository,
+    private val userApi: UserApi
+) : CoroutineWorker(context, params) {
+
+    override suspend fun doWork(): Result {
+        val pending = userRepository.getPendingSync()
+        var hasFailure = false
+
+        for (item in pending) {
+            try {
+                when (item.syncStatus) {
+                    SyncStatus.PENDING_CREATE -> userApi.createUser(item.toDto())
+                    SyncStatus.PENDING_UPDATE -> userApi.updateUser(item.id, item.toDto())
+                    SyncStatus.PENDING_DELETE -> userApi.deleteUser(item.id)
+                    else -> continue
+                }
+                userRepository.markSynced(item.id)
+            } catch (e: Exception) {
+                hasFailure = true
+                // Log but continue — sync other items
+            }
+        }
+        return if (hasFailure) Result.retry() else Result.success()
+    }
+}
+
+// Schedule on connectivity restored
+val syncRequest = OneTimeWorkRequestBuilder<SyncWorker>()
+    .setConstraints(Constraints(requiredNetworkType = NetworkType.CONNECTED))
+    .setBackoffCriteria(BackoffPolicy.EXPONENTIAL, 15, TimeUnit.SECONDS)
+    .build()
+WorkManager.getInstance(context).enqueueUniqueWork("sync", ExistingWorkPolicy.KEEP, syncRequest)
+```
+
+**Sync queue implementation (iOS: BGTaskScheduler)**
+```swift
+// Register in AppDelegate/App
+BGTaskScheduler.shared.register(
+    forTaskWithIdentifier: "com.example.myapp.sync",
+    using: nil
+) { task in
+    SyncEngine.shared.performSync(task: task as! BGProcessingTask)
+}
+
+// Schedule sync
+func scheduleSync() {
+    let request = BGProcessingTaskRequest(identifier: "com.example.myapp.sync")
+    request.requiresNetworkConnectivity = true
+    request.requiresExternalPower = false
+    try? BGTaskScheduler.shared.submit(request)
+}
+```
+
+### Conflict Resolution Strategies
+
+**Last Write Wins (LWW)**
+- Simplest strategy: the record with the most recent `updatedAt` timestamp wins
+- Appropriate for: user preferences, profile data where overwriting is acceptable
+- Pitfall: clock skew between client and server can cause older data to win. Always use server time, not client time, as the authoritative timestamp.
+
+```kotlin
+// Server-side merge
+fun mergeUser(local: UserDto, server: UserDto): UserDto =
+    if (local.updatedAt > server.updatedAt) local else server
+```
+
+**Server Wins**
+- On conflict, the server version is always authoritative. Client changes are discarded.
+- Appropriate for: data owned by the server (inventory, pricing), or when conflicts are rare
+- Implementation: on sync, fetch the latest server version and overwrite local changes
+
+**Client Wins**
+- On conflict, the client's offline changes are always applied.
+- Appropriate for: personal data the user expects to control (notes, settings, journal entries)
+- Implementation: send client changes with `If-Unmodified-Since` or ETag; if conflict, apply client version and bump server version
+
+**Three-Way Merge**
+- Merge the base version, client version, and server version to produce a merged result
+- Used for text fields where both sides should be preserved (collaborative editing)
+- Complex to implement correctly — use a CRDT library or operational transform engine rather than writing from scratch
+
+**CRDTs (Conflict-free Replicated Data Types)**
+- Data structures that guarantee convergence without central coordination
+- Appropriate for: collaborative features, distributed sync without a central server
+- Common types: G-Counter (increment only), PN-Counter (increment/decrement), LWW-Register, OR-Set (add/remove set)
+- Libraries: Automerge (Swift+Kotlin), Yjs (cross-platform via Wasm)
+
+### Network State Detection
+
+**Android: ConnectivityManager**
+```kotlin
+val connectivityManager = context.getSystemService<ConnectivityManager>()
+val networkCallback = object : ConnectivityManager.NetworkCallback() {
+    override fun onAvailable(network: Network) { triggerSync() }
+    override fun onLost(network: Network) { pauseSync() }
+}
+connectivityManager.registerDefaultNetworkCallback(networkCallback)
+```
+
+**iOS: NWPathMonitor**
+```swift
+let monitor = NWPathMonitor()
+monitor.pathUpdateHandler = { path in
+    if path.status == .satisfied {
+        Task { await SyncEngine.shared.sync() }
+    }
+}
+monitor.start(queue: DispatchQueue(label: "NetworkMonitor"))
+```
+
+Always debounce network transitions — connectivity can oscillate rapidly when entering/leaving coverage. Implement a minimum stable duration (e.g., 2 seconds of connectivity) before triggering sync.