Skip to content

🚀 Super App Mobile (React Native + Expo)

The Mobile App is built with React Native + Expo and TypeScript, serving as a secure container for dynamically loaded MicroApps. It provides OAuth 2.0 authentication via External IdP, token-based authorization, and a WebView bridge for MicroApp-to-native communication.

Getting Started

Prerequisites

Before setting up the project, ensure you have the following installed:

  • Node.js (v18 or higher)
  • npm package manager
  • Expo CLI: npm install -g @expo/cli
  • Git for version control

Project Setup

  1. Clone the Repository

    git clone <repository-url>
cd superapp-mobile/frontend

  2. Install Dependencies

    npm install

  3. Environment Configuration

    cp .env.example .env

    Fill in the required environment variables in .env:

    • Authentication
      • Explicit endpoints (recommended)
        • EXPO_PUBLIC_TOKEN_URL
        • EXPO_PUBLIC_CLIENT_ID
        • EXPO_PUBLIC_REDIRECT_URI
        • EXPO_PUBLIC_LOGOUT_URL
    • APP Metadata
      • APP_NAME
      • APP_SLUG
      • APP_SCHEME
      • APP_VERSION
      • APP_OWNER
      • BUNDLE_IDENTIFIER
      • ANDROID_PACKAGE
    • Backend
      • BACKEND_BASE_URL
    • Other Services
      • EXPO_PUBLIC_EVENTS_URL
      • EXPO_PUBLIC_NEWS_URL
    • Optional
      • USE_BACKEND_TOKEN_EXCHANGE ("true"|"false", default true)
      • OpenTelemetry: set EXPO_PUBLIC_OTEL_ENABLED=true to enable metrics during development and add EXPO_PUBLIC_OTEL_COLLECTOR_URL

    Create a folder named google-services inside frontend/ and include the Firebase artifacts ( google-services.json and GoogleService-Info.plist) inside it.

    For branding changes, refer to the assets folder and constant/colors.ts.

  4. Start Development Server

    # Android
npx expo prebuild --platform android --clean // To pre-build the package
npx expo run:android

# iOS Simulator
npx expo prebuild --platform ios --clean
npx expo run:ios

🚀 Deployment

Build Process

Pre-build Native Projects

# Android only
npx expo prebuild --platform android --clean

# iOS only
npx expo prebuild --platform ios --clean

# Both platforms
npx expo prebuild --clean

Android Build

Navigate to the Android folder and build:

cd android
./gradlew assembleRelease

The resulting APK will be in android/app/build/outputs/apk/release/.

iOS Build

Use either Xcode or command line:

# Build for archiving
xcodebuild archive \
  -workspace YourAppName.xcworkspace \
  -scheme YourSchemeName \
  -configuration Release \
  -archivePath build/YourAppName.xcarchive

# Export the IPA
xcodebuild -exportArchive \
  -archivePath build/YourAppName.xcarchive \
  -exportPath build/ipa \
  -exportOptionsPlist ExportOptions.plist

More Details

You can start development by editing the files inside the app directory. This project uses file-based routing.

Production Builds Using EAS Build

# Using EAS Build
npx eas build --platform android
npx eas build --platform ios

# Or using Expo Application Services
npx expo build:android
npx expo build:ios

🏗️ Architecture Overview

Technology Stack

  • Framework: React Native with Expo (SDK 52+)
  • Language: TypeScript
  • Architecture: MVVM (Model-View-ViewModel)
  • Navigation: Expo Router (file-based routing)
  • State Management: Redux Toolkit + Redux Persist
  • Authentication: OAuth 2.0 / OIDC via External IdP
  • Storage:
  • expo-secure-store - Encrypted storage for sensitive data (auth tokens, user configs)
  • @react-native-async-storage/async-storage - General storage for non-sensitive data
  • Styling: React Native StyleSheet + Custom components
  • HTTP Client: Axios
  • Testing: Jest + React Native Testing Library
  • E2E Testing: Maestro

🔒 Security & Data Storage

Storage Strategy

The app uses a dual-storage approach for optimal security and performance:

🔐 SecureStore (Encrypted Storage)

  • Authentication tokens: Access tokens, refresh tokens, ID tokens
  • User configurations: Settings that may contain sensitive preferences
  • Implementation: utils/secureStorage.ts wrapper that automatically routes sensitive keys to expo-secure-store

📦 AsyncStorage (General Storage)

  • App catalog: Micro-app metadata (names, descriptions, icons)
  • User display info: Read-only user info for UI display (name, email)
  • Cache data: News feed, events (non-sensitive, temporary data)

Security Features

  • Token-based authentication with automatic refresh
  • Encrypted storage for authentication credentials
  • Secure token exchange for micro-app access
  • Automatic token expiration handling
  • Secure logout with complete token cleanup

High-Level Mobile App Flow

  1. First launch

    • If the user is not authenticated, the Login screen is shown.
    • After successful sign-in, the app initializes user profile and configuration.

  2. Landing experience (authenticated)

    • Default landing tab is Feed.
    • Tabs available: Feed, My Apps, Profile.

  3. Authentication

    • Retrieve access_token & refresh_token via the IdP and store them in encrypted storage.
    • Fetch user configurations and profile info.
    • Align locally installed micro-apps with server-side configuration (install/uninstall as needed).

  4. Using the app

    • Feed shows the latest content.
    • My Apps lists the user's micro-apps.
    • Profile provides account details and the sign-out option.

  5. On re-open

    • If a valid session exists, the app opens directly to the tabs (Feed by default).
    • Checks for a Super App force update; if required, the update screen is shown.
    • Checks if any micro-apps have updates and updates them automatically.

🧪 Testing

This project includes unit and integration tests following industry best practices.

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run tests in CI mode
npm run test:ci

# Update test snapshots
npm run test:update

📚 Additional Resources

Documentation