Native Mobile Application Architecture (Capacitor 8)

This document is the authoritative engineering specification for the native mobile application packaging of the Debelu marketplace. Grounded directly in [capacitor.config.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/capacitor.config.ts), [nativeApp.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/src/native/nativeApp.ts), [nativePush.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/src/services/nativePush.ts), and the native project directories (apps/storefront/android/ and apps/storefront/ios/), this specification details the hybrid WebView architecture, native bridge interfaces, hardware push notification lifecycle, and app store release protocols.

---

1. System Overview & Hybrid Architecture

The Debelu mobile app wraps the production React 19 / Vite 6 single-page storefront application (@debelu/storefront) into native Android and iOS binary packages utilizing Capacitor 8.5. This hybrid approach enables 100% code reuse across web and mobile surfaces while delivering native hardware integrations, including Apple Push Notification service (APNs), Firebase Cloud Messaging (FCM), universal deep linking, and device haptics.

graph TD
    subgraph MobileDevice [Mobile Device: Android / iOS]
        NativeOS[Native Operating System: Android / iOS Runtime]
        CapacitorRuntime[Capacitor 8.5 Bridge Layer]
        
        subgraph HardwarePlugins [Capacitor Core Plugins]
            Push[PushNotifications Plugin]
            AppLinks[App URL / Universal Links Plugin]
            Splash[SplashScreen Plugin]
            Haptics[Haptics / Vibration API]
        end

        subgraph EmbeddedWebView [Secure Native WebView: app.debelu.com]
            StorefrontApp[React 19 / Vite Storefront SPA]
            NativeAppBridge[nativeApp.ts Dispatcher]
            PushSync[nativePush.ts Device Sync Service]
            OfflineQueue[Service Worker & Offline Cache]
        end
    end

    NativeOS --> CapacitorRuntime
    CapacitorRuntime --> HardwarePlugins
    CapacitorRuntime --> EmbeddedWebView
    
    HardwarePlugins <--> NativeAppBridge
    NativeAppBridge --> StorefrontApp
    PushSync -->|Sync Device Token| BackendAPI[api.debelu.com / Supabase]

1.1 Technical Stack & Core Invariants

• Application ID (Bundle Identifier): com.debelu.app
• Application Display Name: Debelu
• Capacitor Core: @capacitor/core: ^8.5.0
• Platform Runtimes: @capacitor/android: ^8.5.0, @capacitor/ios: ^8.5.0
• Native Plugins:
  • @capacitor/push-notifications: ^8.1.2 (Hardware APNs & FCM push token orchestration)
  • @capacitor/splash-screen: ^8.0.2 (Launch screen management and fade transitions)
  • @capacitor/app: ^8.1.1 (App state changes, backgrounding, and universal deep links)
• Local Web Assets Root: dist (generated via npm run build --workspace=@debelu/storefront)

---

2. Capacitor Configuration Architecture (capacitor.config.ts)

The primary native configuration is declared in [apps/storefront/capacitor.config.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/capacitor.config.ts):

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.debelu.app',
  appName: 'Debelu',
  webDir: 'dist',
  server: {
    androidScheme: 'https',
    iosScheme: 'https',
    hostname: 'app.debelu.com'
  },
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      launchAutoHide: true,
      backgroundColor: '#F5F5F7',
      androidSplashResourceName: 'splash',
      androidScaleType: 'CENTER_CROP',
      showSpinner: false,
      splashFullScreen: true,
      splashImmersive: true
    },
    PushNotifications: {
      presentationOptions: ['badge', 'sound', 'alert']
    }
  }
};

export default config;

2.1 Security & Origin Invariants

1. HTTPS Scheme Binding (server.androidScheme: 'https'): Enforces secure context execution in the Android WebView, allowing modern browser features (Web Crypto, Service Workers, Session Storage) without insecure http:// fallbacks.
2. Canonical Hostname (server.hostname: 'app.debelu.com'): Ties local assets directly to the production origin domain, ensuring cookie isolation, CORS integrity, and automatic SameSite cookie handling.
3. No Cleartext Traffic: Both Android and iOS native manifests disable cleartext HTTP traffic, requiring end-to-end TLS 1.3 encryption.

---

3. Platform Project Structures

3.1 Android Project (apps/storefront/android/)

A standard Gradle-based Android Studio project configured for Android 14+ (API Level 34+):

• app/build.gradle: Configures package namespace, signing configurations, ProGuard / R8 code shrinking rules, and dependencies.
• variables.gradle: Aligns AndroidX and Google Play Services versions across plugins:

  ext {
      minSdkVersion = 24
      compileSdkVersion = 34
      targetSdkVersion = 34
      androidxActivityVersion = '1.8.2'
      androidxAppCompatVersion = '1.6.1'
  }

• AndroidManifest.xml: Declares network security configs, vibration permissions, push notification receivers, and universal link intent filters.

3.2 iOS Project (apps/storefront/ios/)

An Xcode workspace managed via CocoaPods:

• App/Info.plist: Configures status bar styling, universal link association, and push notification entitlement declarations.
• App.entitlements: Declares aps-environment (development or production) and Associated Domains (applinks:app.debelu.com).

---

4. Native Hardware Features & Bridge Engine

The native integration engine [apps/storefront/src/native/nativeApp.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/apps/storefront/src/native/nativeApp.ts) initializes hardware event listeners during app bootstrap:

sequenceDiagram
    autonumber
    participant App as Mobile Hardware / OS
    participant Cap as Capacitor Bridge
    participant NativeApp as nativeApp.ts
    participant Router as router.tsx
    participant Push as nativePush.ts

    App->>Cap: Cold Start / Resume Event
    Cap->>NativeApp: initNativeApp((path) => router.navigate(path))
    
    alt Inbound App Link (Deep Link)
        App->>Cap: Tapped Universal Link (https://app.debelu.com/buy/orders/123)
        Cap->>NativeApp: App.addListener('appUrlOpen')
        NativeApp->>NativeApp: Parse path via appPathFromUrl()
        NativeApp->>Router: router.navigate('/buy/orders/123')
    else Notification Tapped
        App->>Cap: User taps push notification banner
        Cap->>NativeApp: PushNotifications.addListener('pushNotificationActionPerformed')
        NativeApp->>NativeApp: Mark notification read (notificationService.markAsRead)
        NativeApp->>Router: router.navigate(data.url || '/buy')
    end

    Note over NativeApp,Push: Auth Session Change (Member Signs In)
    NativeApp->>Push: nativePush.sync()
    Push->>Cap: Request Push Permissions & Fetch Device Token
    Push-->>NativeApp: Token stored in Supabase user_devices

4.1 Push Notification Lifecycle & Device Privacy (nativePush.ts)

Debelu enforces strict hardware security to protect student privacy on shared mobile devices:

1. Permission Handshake: Automatically prompts for push notification permissions upon sign-in.
2. Token Synchronization: Registers the FCM (Android) or APNs (iOS) device token with the backend, associating it with the authenticated user_id.
3. Automatic Device Unbinding on Sign-Out:

   // apps/storefront/src/native/nativeApp.ts:51-53
   // A shared phone must stop getting the previous member's notifications.
   userService.onBeforeSignOut(() => nativePush.forgetThisDevice());

   When a student logs out, the app immediately revokes the device registration in Supabase, preventing subsequent payment or chat notifications from reaching the next user of the device.

4.2 Universal Deep Linking (appLinks.ts)

• Android App Links: Configured via .well-known/assetlinks.json hosted on app.debelu.com with SHA-256 fingerprint validation.
• Apple Universal Links: Configured via .well-known/apple-app-site-association with Team ID and Bundle ID matching.
• Deep-Link Resolution: Tapped links instantly open the target screen (/buy/product/:id, /buy/orders/:id, /sell/orders/:id) without reloading the web application shell.

4.3 Device Haptics (useHaptic)

Debelu integrates subtle haptic feedback for key interaction checkpoints:

• Selection: Discrete tick on tab switching or campus picker changes.
• Success: Confirmatory vibration on payment completion or order PIN confirmation.
• Warning / Error: Double pulse when ChatGuard flags an off-platform payment attempt.

---

5. Progressive Web App (PWA) Fallback & Offline Engine

When accessed through mobile browsers without native installation, the application operates as an installable Progressive Web App:

1. Web App Manifest (public/manifest.json): Configures standalone display mode, theme colors (#1B5E20 emerald green), campus branding, and maskable application icons.
2. Service Worker (public/sw.js): Implements runtime asset caching, network-first catalog fetching, and offline fallback routing.
3. Offline Invariants: If network connectivity drops while browsing products, useOnlineStatus and useOfflineQueue preserve local cart actions and retry network mutations once cellular connectivity restores.

---

6. Build, Synchronization & Release Workflow

# 1. Compile the web storefront distribution bundle
npm run build --workspace=@debelu/storefront

# 2. Synchronize web assets and plugins to native Android and iOS projects
npm run cap:sync --workspace=@debelu/storefront

# 3. Launch Android Studio for APK / Android App Bundle (AAB) compilation
npm run cap:open:android --workspace=@debelu/storefront

# 4. Launch Xcode for iOS build and TestFlight archiving
npm run cap:open:ios --workspace=@debelu/storefront

6.1 Production Release Checklist

• [ ] Verify version and buildNumber in android/app/build.gradle and ios/App/App.xcodeproj.
• [ ] Confirm Android Keystore release signing credentials.
• [ ] Confirm Apple Developer Team distribution certificate and provisioning profile.
• [ ] Execute Playwright mobile smoke tests (Pixel 5, iPhone 12) to verify responsive layouts.
• [ ] Submit binary to Google Play Console (Closed Testing Track) and Apple App Store Connect (TestFlight).

---

7. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Mobile Architect	Initial enterprise mobile application specification covering Capacitor 8.5 hybrid architecture, push notification privacy, universal deep links, and native project structures.	Active Living Standard