Mobile Push Infrastructure — Developer Guide

Feature: In-House Push Dispatch + Native App Shells
Status: Phase 1 Complete — Native Integration Ready
Subgraphs: alerts, nodes
Repos: ngwenya-ios · ngwenya-android

Overview

The Mobile Push Infrastructure is the platform's native notification delivery layer. Unlike typical implementations that lean on Firebase Admin SDK, Mallnline uses a zero-dependency in-house approach — dispatching directly to Apple Push Notification service (APNs) via HTTP/2 and Firebase Cloud Messaging (FCM) via HTTP v1, using only Node.js built-in http2 and crypto modules.

This architecture ensures:

1. No third-party SDK lock-in — provider switching requires only config changes
2. Full observability — every push flows through the existing AlertDeliveryService DLQ pipeline
3. Platform parity — iOS and Android shells share identical navigation, bridge contracts, and push registration flows

┌──────────────────────────────────────────────────────────────────┐
│                       Native App Layer                           │
│  ┌─────────────────────┐      ┌─────────────────────────────┐   │
│  │  iOS (SwiftUI)      │      │  Android (Jetpack Compose)  │   │
│  │  WKWebView Bridge   │      │  WebView Bridge             │   │
│  │  APNs Token → GQL   │      │  FCM Token → GQL            │   │
│  └──────────┬──────────┘      └──────────┬──────────────────┘   │
└─────────────┼────────────────────────────┼──────────────────────┘
              │ registerPushToken(token,   │
              │ platform: "ios"|"android") │
              ▼                            ▼
┌──────────────────────────────────────────────────────────────────┐
│             Ngwenya Federated Gateway (port 30000)                │
│  ┌──────┐  ┌───────────────────────┐  ┌────────────────────┐    │
│  │ auth │  │ nodes                 │  │ alerts             │    │
│  │      │  │ registerPushToken GQL │  │ PushAlertsService  │    │
│  │      │  │   ─── TCP emit ──►   │  │   APNs HTTP/2      │    │
│  │      │  │                      │  │   FCM HTTP v1      │    │
│  └──────┘  └───────────────────────┘  └────────────────────┘    │
└──────────────────────────────────────────────────────────────────┘

Push Dispatch Service

Architecture

The PushAlertsService in the alerts subgraph handles direct dispatch to both Apple and Google push providers:

Data Flow

sequenceDiagram
    participant App as Native App
    participant GW as Gateway
    participant Nodes as nodes subgraph
    participant Alerts as alerts subgraph
    participant APNs as Apple APNs
    participant FCM as Google FCM

    App->>GW: registerPushToken(token, platform)
    GW->>Nodes: GraphQL mutation
    Nodes->>Nodes: Persist token in User.pushTokens
    Nodes-->>Alerts: TCP: register_push_token

    Note over Alerts: Later, when a notification is triggered...

    Alerts->>Alerts: AlertDeliveryService.sendPush()
    Alerts->>Nodes: TCP: get user push tokens
    Nodes-->>Alerts: [{ token, platform }]
    
    alt platform = ios
        Alerts->>APNs: HTTP/2 POST (JWT auth)
        APNs-->>Alerts: 200 OK / apns-id
    else platform = android
        Alerts->>FCM: HTTPS POST (OAuth2 bearer)
        FCM-->>Alerts: 200 OK / messageId
    end

Graceful Degradation

The service logs a warning and skips dispatch when environment variables are not configured — it never crashes. This allows development and staging environments to run without Apple/Google credentials.

// On module init, the service checks for config:
if (!this.apnsConfig) {
  this.logger.warn('APNs config not set — iOS push disabled');
}
if (!this.fcmConfig) {
  this.logger.warn('FCM config not set — Android push disabled');
}

TCP Event Patterns

Three event patterns connect the nodes subgraph to the alerts push layer:

`register_push_token`

Emitted by UserMutationResolver in the nodes subgraph when a mobile client registers a device token via the registerPushToken GraphQL mutation.

interface RegisterPushTokenDto {
  userId: string;
  token: string;
  platform: 'ios' | 'android';
}

`unregister_push_token`

Emitted on logout or token invalidation via the unregisterPushToken mutation.

interface UnregisterPushTokenDto {
  userId: string;
  token: string;
}

`send_push_notification`

Used by any subgraph to request push dispatch without directly depending on the push infrastructure. This is how murchases, community, and other services trigger mobile pushes.

interface SendPushDto {
  userId: string;
  tokens: string[];   // device tokens (fetched from nodes)
  title: string;
  body: string;
  data?: Record<string, string>;  // deep-link metadata
}

GraphQL API

Register Push Token

mutation RegisterPushToken($token: String!, $platform: String!) {
  registerPushToken(token: $token, platform: $platform) {
    userId
    pushTokens
  }
}

The platform argument ("ios" or "android") is required — it determines which provider the dispatch service uses when sending notifications to this token.

Unregister Push Token

mutation UnregisterPushToken($token: String!) {
  unregisterPushToken(token: $token) {
    userId
  }
}

Native App Shells

Both iOS and Android apps are maintained as independent sub-repos, mounted as git submodules in ngwenya-front:

ngwenya-front/
├── .gitmodules
└── mobile/
    ├── ios/     → github.com/mall-dev/ngwenya-ios
    └── android/ → github.com/mall-dev/ngwenya-android

Tab Navigation (6 Tabs)

Both platforms share the same navigation structure:

iOS Shell (`ngwenya-ios`)

Built with SwiftUI targeting iOS 17+:

Ngwenya/
├── NgwenyaApp.swift              # App entry + APNs delegate
├── Views/
│   ├── ContentView.swift         # 6-tab TabView shell
│   ├── LobbyView.swift           # Native feed
│   ├── MaletView.swift            # WebView delegate
│   ├── UCartView.swift            # Native cart
│   ├── MurchasesView.swift        # Native order history
│   ├── NotificationsView.swift
│   └── UChatView.swift            # Native messaging
├── Bridge/
│   └── WebViewBridge.swift        # WKWebView + JS bridge
└── Services/
    ├── AuthManager.swift          # JWT token management
    └── PushNotificationManager.swift  # GraphQL registration

Push registration flow: AppDelegate receives APNs device token → hex-encodes → calls PushNotificationManager.registerToken(token, platform: "ios") → GraphQL mutation → nodes persists + emits TCP event to alerts.

Android Shell (`ngwenya-android`)

Built with Jetpack Compose + Material3:

com/mallnline/ngwenya/
├── NgwenyaApp.kt                  # Application + notification channel
├── MainActivity.kt               # Compose shell + bottom nav
├── ui/
│   └── Screens.kt                # 6 screen composables
├── services/
│   └── NgwenyaFirebaseService.kt  # FCM token handler
└── bridge/
    └── WebViewBridge.kt           # WebView + token injection

Push registration flow: NgwenyaFirebaseService.onNewToken() receives FCM token → calls PushTokenManager.registerToken(token, "android") → GraphQL mutation → nodes persists + emits TCP event to alerts.

WebView Bridge

Complex Malet storefronts are rendered in a native WebView with auth token injection. This allows the native app to reuse the SvelteKit frontend for screens that aren't yet natively implemented.

Token Injection

Both platforms inject two globals at document start, before page content loads:

window.__NGWENYA_TOKEN__ = '<JWT>';        // Auth token for API calls
window.__NGWENYA_PLATFORM__ = 'ios';       // 'ios' | 'android'

Frontend Detection

The SvelteKit frontend detects WebView context via mobileUtils.ts:

import {
  isMobileWebView,
  getMobilePlatform,
  getNativeAuthToken,
  sendBridgeMessage,
} from '$lib/utils/mobileUtils';

// Check if running inside a native WebView
if (isMobileWebView()) {
  const platform = getMobilePlatform(); // 'ios' | 'android' | null
  const token = getNativeAuthToken();   // JWT or null
}

// Send actions to the native shell
sendBridgeMessage('navigate', { route: '/cart' });
sendBridgeMessage('addToCart', { productId: 'prod_123' });

Bridge API

The sendBridgeMessage() utility in mobileUtils.ts abstracts this difference — frontend code uses a single API regardless of platform.

Navigation Policy

• Links within *.mallnline.com open in the WebView
• External links open in the system browser (Safari / Chrome)

Environment Variables

APNs (iOS Push)

FCM (Android Push)

Graceful degradation: When these variables are not set, the push service logs a warning and returns a no-op. No requests are made to Apple or Google. This is the default behavior in local development.

Module Structure

apps/alerts/src/push-alerts/
├── push-dispatch.interface.ts       # PushPlatform, PushPayload, PushResult, ApnsConfig, FcmConfig
├── push-alerts.service.ts           # APNs HTTP/2 + FCM HTTP v1 dispatch
├── push-alerts.service.spec.ts      # 8 unit tests
├── push-alerts.controller.ts        # TCP event handlers (register/unregister/send)
├── push-alerts.controller.spec.ts   # 4 unit tests
└── push-alerts.module.ts            # NestJS module wiring

Testing

Backend (Alerts Subgraph)

# Run push-alerts unit tests (12 tests across 2 suites)
npm run test -- --testPathPattern=push-alerts

Key test coverage:

• PushAlertsController: Token registration/unregistration logging, cross-service dispatch delegation
• PushAlertsService: Graceful degradation without config, batch dispatch, platform detection, payload formatting

Frontend (WebView Bridge Detection)

# Run mobileUtils unit tests (15 tests)
npx vitest run tests/mobileUtils.test.ts

Key test coverage:

• Platform detection (isMobileWebView, getMobilePlatform, isIOSWebView, isAndroidWebView)
• Token retrieval (getNativeAuthToken) — null, empty string, valid JWT
• Bridge messaging — iOS WKWebView handler, Android JSInterface, missing bridge graceful no-op

Cross-Service Dependency Map

Security Considerations

1. APNs JWT rotation: Tokens are cached for 50 minutes (Apple's max is 60 minutes) and regenerated automatically
2. FCM OAuth2 rotation: Access tokens cached for 58 minutes (Google's max is 3600 seconds) with automatic refresh
3. No keys in source: All provider credentials are loaded from environment variables, never committed to the repository
4. Token injection scope: window.__NGWENYA_TOKEN__ is injected at documentStart (iOS) / onPageFinished (Android), limiting exposure to the WebView context
5. WebView navigation guard: External URLs are intercepted and opened in the system browser, preventing credential harvesting in untrusted contexts
6. Platform validation: Only 'ios' and 'android' are accepted as valid platform values in getMobilePlatform() — any other value returns null

Related

• iOS Development Setup — Xcode project creation, signing, and simulator/device testing
• Android Development Setup — Android Studio, Gradle, Firebase, and emulator setup
• Mobile SDK Architecture — KMP shared module, OIDC/PKCE auth adapters, and uCart widget SDK
• Alerts Resilience & Delivery Tracking — DLQ pipeline and AlertLog that wrap all push dispatch attempts
• Notification Connection Modes — WebSocket vs polling transport for in-app notifications
• Nodes — User Profiles & Social Graph — pushTokens array on the User entity
• Invite & Notification Pipeline — Cross-subgraph event flow for organization notifications
• Handle System & Sigil Taxonomy — v|handle display in native screens
• User Guide: Notifications — Visitor-facing notification management guide