==================
Mobile Application
==================

Repository: ``bridges-mobile-app-source-code/oim-mobile-main``

The beneficiary mobile application is built with **React Native** and **Expo**
(Expo Router for file-based navigation), written in TypeScript. It mirrors the
web experience for beneficiaries who primarily access the platform from a phone.

Technology
==========

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Concern
     - Implementation
   * - Framework
     - React Native + Expo (SDK 54)
   * - Navigation
     - ``expo-router`` (file-based), ``@react-navigation/*``
   * - Language
     - TypeScript
   * - Secure storage
     - ``expo-secure-store`` (tokens)
   * - Local storage
     - ``@react-native-async-storage/async-storage``
   * - i18n / locale
     - ``i18n-js`` + ``expo-localization``
   * - Animations / gestures
     - ``react-native-reanimated``, ``react-native-gesture-handler``
   * - Media / UI
     - ``expo-image``, ``react-native-svg``, ``@expo/vector-icons``

Navigation Structure
====================

The app uses Expo Router route groups under ``app/``:

.. code-block:: text

   app/
     index.tsx                  # entry / redirect
     (onboarding)/              # first-run onboarding
     (auth)/                    # login, register, verify-email,
                                #   forgot/reset-password, reset-code
     (app)/
       (tabs)/                  # main tab navigator
       profile/                 # profile view
       profile-setup/steps/     # multi-step profile completion wizard
       notifications.tsx
       preview-recommendations.tsx

Application Contexts
====================

Global state is provided through React contexts in ``context/``:

.. list-table::
   :header-rows: 1
   :widths: 35 65

   * - Context
     - Responsibility
   * - ``AuthContext``
     - Authentication state, login/logout, token lifecycle
   * - ``BeneficiaryContext``
     - Current beneficiary data
   * - ``ProfileContext``
     - Profile completion state and updates
   * - ``LanguageContext``
     - Active language / locale

Key Components
==============

Reusable components in ``components/`` include ``CompleteProfileModal``,
``ProfileCompletionBanner``, ``FilterModal``, ``RecommendationDetailModal``,
``SessionExpiredModal``, themed primitives (``themed-text``, ``themed-view``),
and ``haptic-tab`` for tactile navigation feedback.

API Service Layer
=================

Network access is centralized in ``services/api``:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - File
     - Responsibility
   * - ``client.ts``
     - Configured HTTP client (base URL, auth headers, interceptors)
   * - ``auth.ts``
     - Authentication endpoints (login, register, password reset)
   * - ``beneficiary.ts``
     - Beneficiary profile and recommendation endpoints
   * - ``reference.ts``
     - Reference / lookup data (regions, sectors, skills)
   * - ``types.ts``
     - Shared request/response types
   * - ``index.ts``
     - Barrel export

User Flows
==========

The mobile app supports onboarding, registration and email verification, a
multi-step profile-setup wizard, viewing and filtering recommendations, viewing
recommendation detail, and managing notifications. Session expiry is handled
gracefully via the ``SessionExpiredModal`` and the ``AuthContext`` token
lifecycle.