ADR-009: Native Mobile Application Strategy

Status

Proposed — Pending engineering team review

Context

The platform currently serves mobile users through Ionic (peeq-mono) — a web-based hybrid approach that wraps the Angular SPA in a Capacitor shell for iOS and Android. The user experience is functionally a web browser in a native wrapper. The business wants a truly native mobile experience alongside the web platform, with dedicated iOS and Android apps.

Current Mobile State

Why Go Native

Decision

Build native mobile apps using React Native with shared business logic between web (Next.js, per ADR-008) and mobile. The shared layer includes TypeScript types, GraphQL operations, authentication logic, and business rules. The UI layer is platform-specific (React for web, React Native for mobile).

Architecture: Shared Monorepo

graph TB
    subgraph "Shared Packages (TypeScript)"
        TYPES[types<br/>Domain models, API types]
        GQL[graphql<br/>Operations, fragments, hooks]
        AUTH[auth<br/>Keycloak client, token mgmt]
        LOGIC[business-logic<br/>Validation, formatting, rules]
    end

    subgraph "Web (Next.js)"
        WEB_APP[Next.js App Router]
        WEB_UI[React Components<br/>Tailwind CSS]
    end

    subgraph "Mobile (React Native)"
        RN_APP[React Native App]
        RN_UI[Native Components<br/>React Native Paper / Tamagui]
        IOS[iOS Build<br/>Xcode / EAS]
        AND[Android Build<br/>Gradle / EAS]
    end

    subgraph "Backend (Unchanged)"
        API[24+ GraphQL Gateways]
        KC[Keycloak]
    end

    TYPES --> WEB_APP
    TYPES --> RN_APP
    GQL --> WEB_APP
    GQL --> RN_APP
    AUTH --> WEB_APP
    AUTH --> RN_APP
    LOGIC --> WEB_APP
    LOGIC --> RN_APP

    WEB_APP --> WEB_UI
    RN_APP --> RN_UI
    RN_UI --> IOS
    RN_UI --> AND

    WEB_APP -->|GraphQL| API
    RN_APP -->|GraphQL| API
    WEB_APP -->|OAuth2| KC
    RN_APP -->|OAuth2| KC

Shared Code Estimation

Estimated shared code: 40-50% of non-UI codebase. This is significant — it means GraphQL queries, type definitions, validation rules, and auth flows are written once.

React Native Technology Stack

Feature Prioritization (Mobile App)

MVP (Phase 1)

Phase 2

Phase 3

Keycloak Mobile Auth Flow

sequenceDiagram
    participant App as React Native App
    participant Browser as System Browser
    participant KC as Keycloak
    participant API as Backend API

    App->>Browser: Open Keycloak authorize URL (PKCE)
    Browser->>KC: Login page (Magic Link or password)
    KC->>Browser: Authorization code (redirect)
    Browser->>App: Deep link with auth code
    App->>KC: Exchange code for tokens (PKCE verifier)
    KC->>App: Access token + refresh token
    App->>App: Store tokens in SecureStore
    App->>API: GraphQL requests with Bearer token
    API->>App: Responses

Magic Link on mobile: When user requests Magic Link, email/SMS contains a deep link (theagilenetwork://auth/magic?token=xxx) that opens the app directly with the auth token. Requires Universal Links configuration.

Hypothesis Background

Primary: React Native with Expo provides a native mobile experience while sharing 40-50% of code with the Next.js web app, delivering better user experience than the current Ionic wrapper.

• Evidence: Ionic/Capacitor renders in a web-view — users experience web-like performance, not native. React Native renders actual native UI components.
• Evidence: ADR-008 proposes Next.js (React) for web. React + React Native enables the shared monorepo pattern. Angular + separate native (Swift/Kotlin) would have zero code sharing.
• Evidence: The platform’s key mobile features (video playback, chat, payments, push notifications) all have mature React Native SDKs from their respective providers (Mux, Stream Chat, Stripe, Expo).

Alternative 1: Keep Ionic/Capacitor. - Rejected: Ionic provides a mobile presence but not a native experience. Apple has been tightening App Store policies around web-view apps. The platform’s content-rich, video-heavy nature demands native performance.

Alternative 2: Build fully native (Swift for iOS, Kotlin for Android). - Rejected: Requires two separate codebases with zero code sharing. Double the development and maintenance effort. The team would need iOS (Swift/UIKit or SwiftUI) and Android (Kotlin/Jetpack Compose) specialists. React Native achieves 90%+ native performance with a single codebase.

Alternative 3: Flutter. - Rejected: Flutter uses Dart, not JavaScript/TypeScript. Zero code sharing with the Next.js web app. While Flutter produces excellent native UIs, the lack of shared code with the web platform is a dealbreaker for a small team.

Alternative 4: Kotlin Multiplatform (KMM). - Rejected: KMM shares business logic (Kotlin) across iOS/Android but doesn’t help with web (TypeScript). The shared layer would be in Kotlin (mobile) and TypeScript (web) — no actual sharing. Also, the team’s backend is Java/Spring Boot, not Kotlin.

Falsifiability Criteria

• If React Native + Expo cannot integrate with Keycloak Magic Link via deep links → evaluate alternative auth flows or custom native modules
• If Mux React Native SDK provides unacceptable video playback quality compared to native → build custom native video module
• If App Store review rejects the app for any Expo-related reasons → switch to bare React Native workflow
• If shared code between web and mobile is <25% in practice → the monorepo benefit doesn’t justify the architectural complexity; consider separate mobile codebase
• If React Native performance (60fps scrolling, <100ms touch response) doesn’t meet expectations → evaluate native Swift/Kotlin for performance-critical screens

Evidence Quality

Overall: L1 (WLNK capped by shared code estimate L0 and current app performance data L0)

Bounded Validity

• Scope: Fan-facing mobile experience (iOS + Android). Expert and admin functionality remain web-only initially. Expert mobile app is Phase 3 consideration.
• Expiry: Re-evaluate if React Native introduces breaking architectural changes, or if Kotlin Multiplatform matures to support web targets effectively.
• Review trigger: If Expo SDK limitations block critical features (specific native modules not available), or if Apple/Google platform APIs move faster than React Native ecosystem can adapt.
• Monitoring: App Store ratings, crash-free rate (>99.5%), cold start time (<2s), video playback quality metrics, user engagement compared to web.

Consequences

Positive: - True native mobile experience (60fps, native navigation, platform-standard UX) - 40-50% code sharing with web via shared monorepo - Consistent GraphQL API usage across web and mobile - OTA updates via EAS (ship fixes without App Store review) - Access to all native APIs (biometrics, push, camera, PiP video) - Deep linking for marketing and sharing - Single team can maintain web + mobile (React skills transfer)

Negative: - New codebase to build and maintain (even with code sharing) - Expo managed workflow has some native module limitations (escape hatch: bare workflow) - App Store review process adds deployment friction - Need to implement Keycloak Magic Link deep linking - Native video player integration requires testing across devices - Must maintain App Store listings, screenshots, descriptions

Mitigated by: Expo simplifies native builds and OTA updates. Stream Chat, Mux, and Stripe all provide maintained React Native SDKs — no custom native bridges needed for core features. Shared monorepo means business logic changes automatically propagate to mobile.

Decision date: 2026-01-31 Review by: 2026-07-31