@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/mobile-app/mobile-app-project-structure.md

@@ -0,0 +1,245 @@
+---
+name: mobile-app-project-structure
+description: Platform directory layout, shared code modules, asset management, and per-environment configuration for iOS and Android mobile apps
+topics: [mobile-app, project-structure, ios, android, assets, configuration, modules]
+---
+
+Mobile project structure decisions affect build times, code sharing, onboarding velocity, and refactoring safety. iOS and Android have platform-mandated directory conventions that tools expect — deviating from them breaks Xcode file resolution, Android Gradle source sets, and code-generation tooling. Within those constraints, module boundaries and shared-code strategies deserve explicit design.
+
+## Summary
+
+iOS projects organize source by feature module under a top-level group matching the app target; Android projects use Gradle modules with `src/main/` source sets per module. Shared business logic lives in a dedicated module (Swift Package, Gradle module, or cross-platform layer). Assets are organized by type and managed through asset catalogs (iOS) or `res/drawable` (Android). Environment configuration uses `.xcconfig` files (iOS) or `BuildConfig` fields in Gradle (Android). Keep feature modules independent — no cross-feature imports.
+
+## Deep Guidance
+
+### iOS Project Structure
+
+**Xcode project layout**
+
+```
+MyApp/
+├── MyApp.xcodeproj/          # Xcode project file (tracked in git)
+├── MyApp.xcworkspace/        # Workspace if using CocoaPods/SPM (tracked)
+├── MyApp/                    # Main app target
+│   ├── App/                  # App entry point
+│   │   ├── MyApp.swift       # @main entry point
+│   │   └── AppDelegate.swift # UIApplicationDelegate (if needed)
+│   ├── Features/             # Feature modules (one folder per feature)
+│   │   ├── Auth/
+│   │   │   ├── Views/
+│   │   │   ├── ViewModels/
+│   │   │   ├── Models/
+│   │   │   └── Services/
+│   │   ├── Profile/
+│   │   └── Home/
+│   ├── Core/                 # Shared utilities, extensions, base classes
+│   │   ├── Extensions/
+│   │   ├── Utilities/
+│   │   └── Base/
+│   ├── Services/             # App-wide services (networking, analytics, storage)
+│   │   ├── Network/
+│   │   ├── Storage/
+│   │   └── Analytics/
+│   ├── Resources/            # Assets and resources
+│   │   ├── Assets.xcassets   # Images, colors, app icon
+│   │   ├── Localizable.strings
+│   │   └── Info.plist
+│   └── Supporting Files/
+│       └── Configuration/    # .xcconfig files
+│           ├── Debug.xcconfig
+│           ├── Release.xcconfig
+│           └── Shared.xcconfig
+├── MyAppTests/               # Unit test target
+├── MyAppUITests/             # UI test target
+└── Packages/                 # Local Swift packages (optional)
+    └── MyAppCore/            # Shared business logic package
+```
+
+**Swift Package Manager for modularization**
+- Local packages declared in the project: `File > Add Package Dependencies > Add Local...`
+- Package.swift defines module boundaries explicitly with product declarations
+- Each local package can export only its public API — private implementation is hidden
+- Move business logic, networking, and data models into packages early; Xcode compilation is parallelized per package
+
+**File organization within feature**
+- One file per type: `LoginView.swift`, `LoginViewModel.swift`, `AuthRepository.swift`
+- Group by role, not by type: `Auth/Views/LoginView.swift` not `Views/LoginView.swift`
+- Avoid mega-files. When a file exceeds ~200 lines, consider extraction.
+
+### Android Project Structure
+
+**Gradle multi-module layout**
+
+```
+MyApp/
+├── app/                          # Main application module
+│   ├── src/
+│   │   ├── main/
+│   │   │   ├── java/com/example/myapp/
+│   │   │   │   ├── MainActivity.kt
+│   │   │   │   └── MyApplication.kt
+│   │   │   ├── res/
+│   │   │   │   ├── drawable/
+│   │   │   │   ├── layout/        # XML layouts (View system only)
+│   │   │   │   ├── values/
+│   │   │   │   │   ├── colors.xml
+│   │   │   │   │   ├── strings.xml
+│   │   │   │   │   └── themes.xml
+│   │   │   │   └── mipmap/        # App icon (all densities)
+│   │   │   └── AndroidManifest.xml
+│   │   ├── debug/                 # Debug-only sources and resources
+│   │   └── release/               # Release-only sources (e.g., no-op analytics)
+│   └── build.gradle.kts
+├── feature/                       # Feature modules
+│   ├── auth/
+│   │   ├── src/main/java/com/example/myapp/feature/auth/
+│   │   │   ├── AuthScreen.kt
+│   │   │   ├── AuthViewModel.kt
+│   │   │   └── AuthRepository.kt
+│   │   └── build.gradle.kts
+│   ├── profile/
+│   └── home/
+├── core/                          # Core shared modules
+│   ├── data/                      # Repositories, data sources
+│   ├── domain/                    # Use cases, domain models
+│   ├── network/                   # Retrofit, OkHttp, interceptors
+│   ├── storage/                   # Room, DataStore, Keychain
+│   ├── ui/                        # Shared Compose components, theme
+│   └── testing/                   # Test utilities and fakes
+├── build.gradle.kts               # Root build file
+├── settings.gradle.kts            # Module declarations
+└── gradle/
+    ├── libs.versions.toml         # Version catalog
+    └── wrapper/
+```
+
+**Dependency rules (enforced with lint or Dependency Guard)**
+- `app` can depend on `feature/*` and `core/*`
+- `feature/*` can depend on `core/*` only — never on other features
+- `core/domain` has no Android dependencies — pure Kotlin
+- `core/data` depends on `core/domain`; `core/network` depends on `core/data`
+- Circular dependencies between modules will break the build — the structure prevents them
+
+**Version catalog (`libs.versions.toml`)**
+```toml
+[versions]
+kotlin = "2.0.0"
+compose-bom = "2024.09.00"
+hilt = "2.51"
+
+[libraries]
+compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "compose-bom" }
+hilt-android = { group = "com.google.dagger", name = "hilt-android", version.ref = "hilt" }
+
+[plugins]
+android-application = { id = "com.android.application", version = "8.6.0" }
+kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+hilt = { id = "com.google.dagger.hilt.android", version.ref = "hilt" }
+```
+
+### Asset Management
+
+**iOS Assets.xcassets**
+- All images must be in an asset catalog — never load images from bare file paths at runtime
+- Image sets: provide 1x, 2x, 3x for bitmap assets; prefer PDF or SVG (Universal) for icons and vector art
+- Color sets: define semantic color pairs (light/dark) in the asset catalog, not in code. Name them by semantic role: `PrimaryText`, `Background`, `AccentColor`
+- App Icon set: Xcode 15+ accepts a single 1024×1024 image and generates all sizes automatically
+- Symbol sets: for custom SF-Symbol-style icons, add `.svg` files as symbol sets
+- Namespace asset catalogs using folder names with `.xcassets` grouping: `Icons.xcassets`, `Images.xcassets`, `Colors.xcassets`
+
+**Android drawable resources**
+- Vector drawables (`.xml`) for all icons — scale perfectly on any density
+- Bitmap assets: provide `mdpi`, `hdpi`, `xhdpi`, `xxhdpi`, `xxxhdpi` variants in separate `drawable-*` folders, or use Android Studio's vector import to auto-generate
+- Night mode: place dark-mode variants in `drawable-night/` and `values-night/colors.xml`
+- Adaptive icons (`res/mipmap-anydpi-v26/ic_launcher.xml`): required for Android 8.0+; foreground + background layers
+- App icon: 512×512 PNG for Play Store; adaptive icon XML for device display
+- Localized strings: `values/strings.xml` (default), `values-es/strings.xml` (Spanish), etc.
+
+### Environment Configuration
+
+**iOS — xcconfig files**
+```
+# Shared.xcconfig
+BASE_URL = https$(inherited)://api.myapp.com
+
+# Debug.xcconfig
+#include "Shared.xcconfig"
+BASE_URL = https://api-dev.myapp.com
+BUNDLE_ID_SUFFIX = .debug
+
+# Release.xcconfig
+#include "Shared.xcconfig"
+BASE_URL = https://api.myapp.com
+BUNDLE_ID_SUFFIX =
+```
+
+Access in code via `Info.plist` (read xcconfig variables into plist) then:
+```swift
+let baseURL = Bundle.main.infoDictionary?["BASE_URL"] as? String ?? ""
+```
+
+**Never hardcode secrets in xcconfig** — these are tracked in git. Use the iOS Keychain for runtime secrets or load from a non-tracked `.env.xcconfig` file that is gitignored.
+
+**Android — BuildConfig fields**
+```kotlin
+// build.gradle.kts (app module)
+android {
+    buildTypes {
+        debug {
+            buildConfigField("String", "BASE_URL", "\"https://api-dev.myapp.com\"")
+            applicationIdSuffix = ".debug"
+        }
+        release {
+            buildConfigField("String", "BASE_URL", "\"https://api.myapp.com\"")
+        }
+    }
+}
+```
+
+Access in code: `BuildConfig.BASE_URL`
+
+**Product flavors for multi-environment builds**
+```kotlin
+flavorDimensions += "environment"
+productFlavors {
+    create("staging") {
+        dimension = "environment"
+        buildConfigField("String", "BASE_URL", "\"https://api-staging.myapp.com\"")
+    }
+    create("production") {
+        dimension = "environment"
+        buildConfigField("String", "BASE_URL", "\"https://api.myapp.com\"")
+    }
+}
+```
+
+**Secrets management**
+- Never commit API keys, signing credentials, or OAuth secrets to git
+- iOS: use `local.xcconfig` (gitignored) that overrides base config, or environment variables in CI
+- Android: `local.properties` (gitignored) for local overrides; CI injects via environment variables
+- At runtime: fetch secrets from a secrets manager (AWS Secrets Manager, HashiCorp Vault) or use platform secure storage (Keychain, Keystore) seeded during onboarding
+
+### Cross-Platform Shared Code
+
+**Swift Package for shared logic (iOS only or iOS + macOS)**
+```swift
+// Package.swift
+let package = Package(
+    name: "AppCore",
+    platforms: [.iOS(.v16), .macOS(.v13)],
+    products: [
+        .library(name: "AppCore", targets: ["AppCore"]),
+    ],
+    targets: [
+        .target(name: "AppCore", path: "Sources/AppCore"),
+        .testTarget(name: "AppCoreTests", dependencies: ["AppCore"])
+    ]
+)
+```
+
+**Kotlin Multiplatform (iOS + Android)**
+- `commonMain`: pure Kotlin business logic, domain models, use cases
+- `iosMain`: iOS-specific implementations of `expect` declarations
+- `androidMain`: Android-specific implementations
+- UI remains platform-native (SwiftUI for iOS, Compose for Android)
+- Data layer: `commonMain` repositories with platform-specific database drivers (`SQLDelight` handles this)

package/content/knowledge/mobile-app/mobile-app-push-notifications.md

@@ -0,0 +1,321 @@
+---
+name: mobile-app-push-notifications
+description: APNs and FCM setup, notification channels, rich notifications, background handling, and permission best practices for mobile apps
+topics: [mobile-app, push-notifications, apns, fcm, firebase, notification-channels, rich-notifications, background]
+---
+
+Push notifications are a direct channel to re-engage users, but they are also the fastest way to lose them: irrelevant or excessive notifications get disabled or trigger uninstalls. The technical implementation requires setting up APNs (Apple Push Notification service) for iOS and FCM (Firebase Cloud Messaging) for Android, managing device tokens, and handling notifications in all app states (foreground, background, terminated). Get the permission request timing right — it determines your opt-in rate.
+
+## Summary
+
+iOS push requires APNs certificate or key setup, `UNUserNotificationCenter` for permission and handling, and a device token registered with your backend. Android push uses FCM with notification channels (required for Android 8.0+) and `FirebaseMessagingService` for token and message handling. Both platforms support rich notifications (images, actions, custom UI). Permission requests must explain value before asking — iOS grants are permanent opt-outs if declined. Handle notifications in all three app states: foreground, background, and terminated.
+
+## Deep Guidance
+
+### iOS: APNs Setup
+
+**APNs authentication options**
+
+*APNs Key (recommended)*
+- Create an APNs authentication key in the Apple Developer portal: Certificates, Identifiers & Profiles > Keys
+- Download the `.p8` file — this is valid for all apps and does not expire
+- Key credentials: Key ID (10 characters) + Team ID + `.p8` file
+- Never commit the `.p8` file to git — store in a secrets manager
+
+*APNs Certificate (legacy)*
+- Certificate expires annually — requires renewal
+- App-specific — one certificate per bundle ID
+- Use key-based auth for all new integrations
+
+**Xcode capability setup**
+1. Add "Push Notifications" capability in Xcode > Target > Signing & Capabilities
+2. Add "Background Modes" capability and check "Remote notifications" for silent/background pushes
+3. Xcode adds the `aps-environment` entitlement automatically
+
+**Device token registration (Swift)**
+```swift
+// AppDelegate or @main App struct
+class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
+    ) {
+        let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
+        // Send token to your backend
+        Task { await PushTokenService.shared.registerToken(token) }
+    }
+
+    func application(
+        _ application: UIApplication,
+        didFailToRegisterForRemoteNotificationsWithError error: Error
+    ) {
+        // Simulators always fail here — log but don't treat as fatal in debug
+        print("Push registration failed: \(error)")
+    }
+}
+```
+
+**Permission request (timing matters)**
+```swift
+func requestPushPermission() async {
+    let center = UNUserNotificationCenter.current()
+    let settings = await center.notificationSettings()
+    guard settings.authorizationStatus == .notDetermined else { return }
+
+    // Only ask after providing value context — e.g., after first order placed
+    let granted = try? await center.requestAuthorization(options: [.alert, .badge, .sound])
+    if granted == true {
+        await MainActor.run {
+            UIApplication.shared.registerForRemoteNotifications()
+        }
+    }
+}
+```
+
+Rules for permission timing:
+- Never ask on first launch — users have not yet experienced value
+- Ask after a meaningful action: first order, first message received, or explicit "Enable notifications" tap in settings UI
+- If denied, guide users to Settings rather than asking again (iOS prevents re-prompting)
+
+**Notification handling (all app states)**
+```swift
+extension AppDelegate: UNUserNotificationCenterDelegate {
+    // Foreground: notification arrives while app is active
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        willPresent notification: UNNotification,
+        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void
+    ) {
+        // Decide whether to show banner while app is open
+        completionHandler([.banner, .sound, .badge])
+    }
+
+    // User tapped notification (foreground or background)
+    func userNotificationCenter(
+        _ center: UNUserNotificationCenter,
+        didReceive response: UNNotificationResponse,
+        withCompletionHandler completionHandler: @escaping () -> Void
+    ) {
+        let userInfo = response.notification.request.content.userInfo
+        // Handle deep link or action
+        handleNotificationTap(userInfo: userInfo)
+        completionHandler()
+    }
+}
+
+// Silent background notification (content-available: 1)
+func application(
+    _ application: UIApplication,
+    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
+    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
+) {
+    Task {
+        await SyncEngine.shared.syncOnPushReceived()
+        completionHandler(.newData)
+    }
+}
+```
+
+### Android: FCM Setup
+
+**Firebase project setup**
+1. Create project in Firebase Console
+2. Add Android app with the package name
+3. Download `google-services.json` and place in `app/` directory (not project root)
+4. Add to `build.gradle.kts`: `apply plugin: "com.google.gms.google-services"`
+
+**FCM Service implementation**
+```kotlin
+@AndroidEntryPoint
+class MyFirebaseMessagingService : FirebaseMessagingService() {
+
+    @Inject lateinit var pushTokenRepository: PushTokenRepository
+    @Inject lateinit var notificationManager: AppNotificationManager
+
+    // Token refresh — called on first run and when token changes
+    override fun onNewToken(token: String) {
+        super.onNewToken(token)
+        // Send to backend — use WorkManager to ensure delivery even if offline
+        pushTokenRepository.scheduleTokenUpload(token)
+    }
+
+    // Data message received (app in foreground or background)
+    override fun onMessageReceived(message: RemoteMessage) {
+        super.onMessageReceived(message)
+        when (message.data["type"]) {
+            "chat_message" -> handleChatMessage(message)
+            "order_update" -> handleOrderUpdate(message)
+            else -> notificationManager.showGenericNotification(message)
+        }
+    }
+
+    private fun handleChatMessage(message: RemoteMessage) {
+        notificationManager.showChatNotification(
+            title = message.data["sender_name"] ?: "New message",
+            body = message.data["preview"] ?: "",
+            conversationId = message.data["conversation_id"] ?: return
+        )
+    }
+}
+```
+
+**Notification channels (Android 8.0+ requirement)**
+```kotlin
+class AppNotificationManager @Inject constructor(
+    private val context: Context,
+    private val notificationManager: NotificationManagerCompat
+) {
+    companion object {
+        const val CHANNEL_CHAT = "chat_messages"
+        const val CHANNEL_ORDERS = "order_updates"
+        const val CHANNEL_PROMOTIONS = "promotions"
+    }
+
+    fun createChannels() {
+        val channels = listOf(
+            NotificationChannel(CHANNEL_CHAT, "Chat Messages", NotificationManager.IMPORTANCE_HIGH).apply {
+                description = "Messages from other users"
+                enableVibration(true)
+            },
+            NotificationChannel(CHANNEL_ORDERS, "Order Updates", NotificationManager.IMPORTANCE_DEFAULT).apply {
+                description = "Updates on your orders"
+            },
+            NotificationChannel(CHANNEL_PROMOTIONS, "Promotions", NotificationManager.IMPORTANCE_LOW).apply {
+                description = "Deals and offers — can be disabled without affecting order updates"
+            }
+        )
+        notificationManager.createNotificationChannels(channels)
+    }
+}
+```
+
+Channel importance rules:
+- `IMPORTANCE_HIGH`: chat, time-sensitive alerts — shows heads-up notification
+- `IMPORTANCE_DEFAULT`: order updates, reminders — shows in notification shade
+- `IMPORTANCE_LOW`: promotions, non-urgent — no sound/vibration
+- `IMPORTANCE_MIN`: silent, no icon in status bar — rarely useful
+
+Separate channels by user concern, not by technical category. Users can disable individual channels in Settings — respect their choices.
+
+**Showing a notification**
+```kotlin
+fun showChatNotification(title: String, body: String, conversationId: String) {
+    val intent = Intent(context, MainActivity::class.java).apply {
+        putExtra("destination", "chat/$conversationId")
+        flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
+    }
+    val pendingIntent = PendingIntent.getActivity(
+        context, conversationId.hashCode(), intent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+    )
+
+    val notification = NotificationCompat.Builder(context, CHANNEL_CHAT)
+        .setSmallIcon(R.drawable.ic_notification)
+        .setContentTitle(title)
+        .setContentText(body)
+        .setAutoCancel(true)
+        .setContentIntent(pendingIntent)
+        .setPriority(NotificationCompat.PRIORITY_HIGH)
+        .build()
+
+    notificationManager.notify(conversationId.hashCode(), notification)
+}
+```
+
+### Rich Notifications
+
+**iOS: Notification Service Extension**
+For modifying notification content before display (decrypting, downloading media):
+1. Add a Notification Service Extension target in Xcode
+2. Implement `UNNotificationServiceExtension`:
+
+```swift
+class NotificationService: UNNotificationServiceExtension {
+    override func didReceive(
+        _ request: UNNotificationRequest,
+        withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+    ) {
+        let content = request.content.mutableCopy() as! UNMutableNotificationContent
+
+        // Download and attach image
+        if let imageURL = content.userInfo["image_url"] as? String,
+           let url = URL(string: imageURL),
+           let attachment = try? UNNotificationAttachment(
+               identifier: "image",
+               url: downloadImage(from: url),  // must download synchronously or with semaphore
+               options: nil
+           ) {
+            content.attachments = [attachment]
+        }
+        contentHandler(content)
+    }
+}
+```
+
+**iOS: Notification Content Extension**
+For fully custom notification UI:
+- Add a Notification Content Extension target
+- Set `UNNotificationExtensionCategory` in the Info.plist to the APNs category string
+- Implement `UNNotificationContentExtension` in the ViewController
+
+**Android: Big notifications**
+```kotlin
+// Expandable text
+NotificationCompat.Builder(context, CHANNEL_ORDERS)
+    .setStyle(NotificationCompat.BigTextStyle().bigText(longBody))
+
+// Image notification
+NotificationCompat.Builder(context, CHANNEL_CHAT)
+    .setStyle(NotificationCompat.BigPictureStyle().bigPicture(bitmap))
+
+// Conversation (messaging style — shows thread)
+NotificationCompat.Builder(context, CHANNEL_CHAT)
+    .setStyle(NotificationCompat.MessagingStyle("You")
+        .addMessage("Hello!", timestamp, sender)
+        .addMessage("How are you?", timestamp2, sender)
+    )
+```
+
+**Notification actions**
+```kotlin
+// Android action buttons
+val replyAction = NotificationCompat.Action.Builder(
+    R.drawable.ic_reply, "Reply",
+    PendingIntent.getBroadcast(context, 0, replyIntent, PendingIntent.FLAG_MUTABLE)
+).addRemoteInput(
+    RemoteInput.Builder("reply_text").setLabel("Reply...").build()
+).build()
+
+NotificationCompat.Builder(context, CHANNEL_CHAT)
+    .addAction(replyAction)
+    .addAction(R.drawable.ic_mark_read, "Mark as read", markReadPendingIntent)
+```
+
+### Token Lifecycle Management
+
+**Token refresh handling**
+- Both APNs tokens (iOS) and FCM tokens (Android) can change: on reinstall, OS update, or after long inactivity
+- Always store the token server-side with a device identifier
+- Implement token refresh callbacks (`onNewToken` for FCM, `didRegisterForRemoteNotificationsWithDeviceToken` for APNs) and sync to backend
+- Store multiple tokens per user (one per device)
+- Clean up invalid tokens: when sending to a token returns a 404 (APNs) or `InvalidRegistration` (FCM), remove it from your database
+
+**Server-side notification delivery**
+```javascript
+// Firebase Admin SDK
+const message = {
+    notification: { title: "New message", body: "Jane says hi" },
+    data: { type: "chat_message", conversation_id: "abc123" },
+    apns: {
+        payload: { aps: { sound: "default", badge: 1 } }
+    },
+    android: {
+        priority: "high",
+        notification: { channel_id: "chat_messages" }
+    },
+    token: deviceToken
+};
+await admin.messaging().send(message);
+```
+
+Always send both `notification` and `data` payloads for maximum compatibility — `notification` payloads are handled by the system when the app is in the background, `data` payloads require app code to handle.