Mobile App Overview

Mobile App Overview

The Merq Mobile application is a cross-platform tool for field force agents, built with React Native. Its primary design principle is offline-first, ensuring that agents can perform their duties reliably even in areas with poor or no internet connectivity.

The app uses a curated and strict technology stack to enforce consistency and performance, centered around React Native Paper (MD3) for UI, MMKV for storage, and TanStack Query for data synchronization.

Framework

React Native 0.80

UI Library

React Native Paper MD3

Storage

MMKV (Mandatory)

Core Principle

Offline-First

Core Features & Scope

The mobile app is the primary tool for field agents:

• Offline-First Operation: All core functions—such as viewing visit schedules, accessing outlet details, and submitting visit data—are designed to work without an internet connection. Data is stored locally and synchronized with the backend when connectivity is available.
• Visit Management: Agents can view their daily visit schedules, check-in/check-out of outlets, and record visit outcomes.
• Data Submission: Provides forms for various submission types (e.g., stock count, photo evidence, surveys), which are saved locally and uploaded in the background.
• Geolocation & Geofencing: Uses device GPS to verify agent location for check-ins and track visit routes.
• Camera Integration: Utilizes the device camera for tasks like barcode scanning and capturing photo evidence.
• Push Notifications: Receives real-time updates and instructions from the backend via Firebase Cloud Messaging (FCM).
• Secure Local Storage: All sensitive data is stored on the device using MMKV, a fast and encrypted key-value storage library.

Caution

Strict Convention: The project strictly forbids the use of AsyncStorage or SQLite. All local persistence must be implemented using the provided MMKV helpers in src/core/storage/.

Key Technical Decisions

The mobile stack is carefully selected to support the offline-first requirement and ensure a high-quality user experience:

• React Native: Allows for cross-platform development (iOS and Android) from a single codebase.
• React Native Paper (MD3): A material design component library that provides a consistent and high-quality set of UI elements. The project enforces the use of Paper components only, preventing the introduction of other UI libraries.
• MMKV: A high-performance, encrypted, and synchronous key-value storage library. It is significantly faster than AsyncStorage and is the mandatory choice for all local data persistence.
• TanStack Query: Used for both server state management and offline synchronization. All queries are configured with networkMode: 'offlineFirst', which seamlessly handles data fetching from the cache when offline and synchronizing with the server when online.
• Jotai: A lightweight global state manager for client-side state, such as the current authentication status or user profile.
• FlashList: A performant list component from Shopify, used for all long lists to ensure a smooth scrolling experience, even with thousands of items.
• Reanimated & Vision Camera: Used for high-performance animations and advanced camera functionalities, respectively, ensuring a native-like feel.
• Named Exports & Barrel Files: The project mandates the use of named exports and barrel files (index.ts) for all modules to improve code organization and maintainability.