Mobile SDK Architecture

Feature: Native Mobile Auth (OIDC) + Kotlin Multiplatform uCart SDK
Status: Scaffolding Complete — Ready for Native Integration
Subgraphs: auth, ucart, gateway

Overview

The Ngwenya Mobile SDK provides native iOS and Android applications with the same uCart widget capabilities available on the web: product browsing, cart management, and authenticated checkout — all powered by the federated GraphQL gateway.

The architecture is split into two layers:

1. Mobile Auth Adapters — Platform-specific OIDC authentication flows
2. KMP Shared Module — Cross-platform business logic in Kotlin Multiplatform

graph TD
    subgraph Native["Native App Layer"]
        iOS["iOS (Swift/SwiftUI)"]
        Android["Android (Kotlin/Compose)"]

        subgraph KMP["KMP Shared Module (commonMain)"]
            UCartApi["UCartApi"]
            UCartState["UCartState"]
            AuthAdapter["PlatformAuthAdapter"]
            Models["Models (@Serializable)"]
        end

        subgraph AuthLayer["TypeScript Auth Adapter Layer"]
            WebAdapter["WebAdapter (popup)"]
            NativeRedirect["NativeRedirect (PKCE+system)"]
            NativeWebView["NativeWebView (bridge)"]
        end
    end

    subgraph Gateway["Ngwenya Federated Gateway (:30000)"]
        auth["auth"]
        ucart["ucart"]
        malet["malet"]
        products["products"]
    end

    iOS --> KMP
    Android --> KMP
    KMP --> AuthLayer
    AuthLayer --> Gateway

Mobile Auth Adapters

Architecture

The auth system uses a platform-agnostic adapter interface (AuthAdapter) with three concrete implementations:

Auth Flow: Native Redirect (Recommended)

┌───────────┐    ┌──────────────┐    ┌──────────────┐    ┌────────────┐
│ Mobile App│    │System Browser│    │ OIDC Provider│    │ Auth Server│
│           │    │              │    │ (Google/Apple)│    │ (Ngwenya)  │
└─────┬─────┘    └──────┬───────┘    └──────┬───────┘    └─────┬──────┘
      │                 │                    │                   │
      │ buildAuthURL()  │                    │                   │
      │ (with PKCE)     │                    │                   │
      ├────────────────►│                    │                   │
      │                 │  Authorization     │                   │
      │                 │  Request           │                   │
      │                 ├───────────────────►│                   │
      │                 │                    │                   │
      │                 │  User authenticates│                   │
      │                 │ ◄──────────────────┤                   │
      │                 │                    │                   │
      │ Deep link       │  Redirect with     │                   │
      │ with code       │  auth code         │                   │
      │◄────────────────┤                    │                   │
      │                 │                    │                   │
      │ exchangeCode()  │                    │                   │
      │ (with verifier) │                    │                   │
      ├─────────────────┼───────────────────►│                   │
      │                 │                    │  OIDC tokens      │
      │◄────────────────┼────────────────────┤                   │
      │                 │                    │                   │
      │ Platform token  │                    │                   │
      │ exchange         │                    │                   │
      ├─────────────────┼────────────────────┼──────────────────►│
      │                 │                    │   Platform JWT     │
      │◄────────────────┼────────────────────┼───────────────────┤
      │                 │                    │                   │
      │ ✅ Authenticated│                    │                   │

PKCE (Proof Key for Code Exchange)

All native auth flows use PKCE for public client security:

import { generatePKCEChallenge } from '$lib/ucart-widget/mobile-auth-adapter';

const pkce = await generatePKCEChallenge();
// pkce.codeVerifier  — 64-char random string (kept secret)
// pkce.codeChallenge — SHA-256 hash, base64url encoded (sent to provider)
// pkce.codeChallengeMethod — always "S256"

Supported OIDC Providers

Redirect URIs

Factory Function

import { createAuthAdapter } from '$lib/ucart-widget/mobile-auth-adapter';

// Auto-detect platform and use recommended strategy
const auth = createAuthAdapter({
    authUrl: 'https://auth.mallnline.io',
    platform: 'ios', // or 'android', 'web', 'react-native'
    redirectUri: 'https://app.mallnline.io/auth/callback',
    clientId: 'your-client-id',
    scopes: ['openid', 'email', 'profile']
});

KMP Shared Module

Architecture

The Kotlin Multiplatform module provides shared business logic that compiles to both iOS frameworks (Kotlin/Native) and Android libraries (Kotlin/JVM).

Source set structure:

• commonMain — Shared API client, state manager, models
• iosMain — Darwin HTTP engine (NSURLSession), Keychain adapter
• androidMain — OkHttp engine, EncryptedSharedPreferences adapter

Dependencies

Shared Models

All models use @Serializable for automatic JSON coding:

@Serializable
data class WidgetProduct(
    val id: String,
    val name: String,
    val description: String,
    val images: List<String>,
    val price: WidgetMoney,
    val compareAtPrice: WidgetMoney? = null,
    val totalInventory: Int,
    val availableForSale: Boolean,
    val variants: List<WidgetProductVariant>,
    val malet: MaletInfo
)

API Client

val api = UCartApi(
    baseUrl = "https://api.mallnline.io",
    getToken = { authAdapter.getToken() }
)

// Load product
val product = api.getProduct("prod_123")

// Add to cart
val cart = api.addToCart(AddToCartPayload(
    productId = "prod_123",
    maletId = "malet_1",
    quantity = 1
))

Reactive State

val state = UCartState(api, authAdapter)

// Observe state changes
state.stateFlow.collect { snapshot ->
    updateUI(
        product = snapshot.product,
        cart = snapshot.cart,
        isLoading = snapshot.isLoading
    )
}

// Trigger operations
state.loadProduct("prod_123")
state.addToCart("prod_123", "malet_1", quantity = 2)

iOS Distribution

Swift Package Manager (preferred):

// Package.swift dependency
.package(url: "https://github.com/mallnline/ngwenya-ucart-kmp", from: "0.1.0")

CocoaPods (fallback):

# Podfile
pod 'NgwenyaUCart', :path => '../kmp/shared'

File Reference

Screen Data Integration

Added 2026-05-03 — KMP shared module now provides data for all 5 native tabs.

Architecture

The KMP shared module uses GraphQL queries against the same federated gateway as the SvelteKit web frontend. No REST wrappers needed — the UCartApi sends raw GraphQL operations via POST /graphql.

graph LR
    subgraph Native["Native UI (SwiftUI / Compose)"]
        ViewModel["ViewModel"]
    end

    subgraph KMP["KMP Shared Module"]
        UCartState["UCartState\nloadFeed() · loadOrders()\nloadNotifs() · loadConvs()"]
        UCartApi["UCartApi\ngraphql() → POST /graphql"]
    end

    Gateway["Ngwenya Federated Gateway"]

    ViewModel -- "StateFlow" --> UCartState
    UCartState --> UCartApi
    UCartApi -- "GraphQL" --> Gateway

Extended KMP API Methods

ViewModel Pattern

iOS (SwiftUI):

@Observable
class NgwenyaViewModel {
    var feedItems: [FeedItem] = []
    var orders: [OrderItem] = []
    // ...
    func loadFeed() { /* KMP: state.loadFeed { items in ... } */ }
}

// Injected via .environment() in NgwenyaApp.swift
ContentView().environment(viewModel)

Android (Compose):

class NgwenyaViewModel : ViewModel() {
    data class ScreenState(
        val feedItems: List<FeedItem> = emptyList(),
        val orders: List<OrderItem> = emptyList(),
        // ...
    )
    private val _state = MutableStateFlow(ScreenState())
    val state: StateFlow<ScreenState> = _state.asStateFlow()

    fun loadFeed() { /* KMP: uCartState.loadFeed { items -> ... } */ }
}

// Created via viewModel() in MainActivity
val viewModel: NgwenyaViewModel = viewModel()

Bridge Data Contract

The web↔native bridge supports screen data exchange:

TypeScript parity types in kmpScreenTypes.ts with Zod schemas enable validation of data shapes exchanged between platforms.

Security Considerations

1. PKCE is mandatory for all native auth flows (prevents authorization code interception)
2. System browser preferred over WebView (prevents credential harvesting)
3. Tokens stored in platform-secure storage (iOS Keychain / Android EncryptedSharedPreferences)
4. Token exchange — OIDC tokens are exchanged for Ngwenya platform JWTs server-side
5. No client secrets — native apps are public clients (PKCE replaces client_secret)

Related Documentation

• Mobile Push Infrastructure — In-house APNs/FCM push dispatch, native app shells, and WebView bridge
• iOS Development Setup — Xcode project creation, signing, and simulator/device testing
• Android Development Setup — Android Studio, Gradle, Firebase, and emulator setup
• uCart Concurrency Resilience — Cart atomic operations
• MFA and Passkeys — Additional auth factors
• Gateway Rate Limiting — Mobile API rate limits
• REST API — Public API endpoints consumed by the widget
• Developer Docs Overview — Back to the main documentation index.