Tech Stack — Mobile

Parent: Tech Stack Overview

Applies to apps/dashboard-mobile — the React Native iOS/Android app targeting client/tenant users only. The DM portal remains web-only.

Framework

Expo managed workflow — not bare. Build and distribution via EAS (Expo Application Services). Metro bundler for development.

New Architecture (Fabric + JSI): Enabled for better scroll performance on large lists and native module interop for biometric auth.

Bundle ID / Package: ai.leadmetrics.mobile

Navigation

Deep link scheme: leadmetrics:// — handles push notification taps and OAuth callback redirects via expo-linking.

State Management

Stale content is shown while fresh data loads. Write mutations (approvals, saves) require connectivity — they are not queued offline.

Forms & Validation

Push Notifications

Token lifecycle: Tokens are registered with the API on first login and updated on rotation via the mobile patterns (crypto.randomUUID for device ID, per-item endpoints). Push device tokens stored in PushDeviceToken model.

Notification types triggered by the platform:

• Activity/approval created or updated
• Agent run completed or failed
• New content ready for client review
• Budget or goal alerts

Authentication

Token flow:

• Access token: in-memory (React state / query client)
• Refresh token: expo-secure-store (OS keychain)
• Silent refresh: AbortController-wrapped fetch with 401 retry
• Unlock session: unlockSession() auth pattern with biometric gate

Local Storage

Animations & Gestures

Real-Time (SSE)

SSE pre-refresh pattern: token is refreshed before opening the SSE connection to avoid mid-stream 401s.

Markdown

UI Patterns

There is no shared component library between web and mobile (web uses custom Tailwind, mobile uses native React Native components).

Mobile-specific patterns:

• FlatList / SectionList for all scrollable lists — never ScrollView for long lists
• Pull-to-refresh on all list screens
• No inline editing (web-only feature) — mobile is read + approve/reject only
• No DM portal actions — mobile is client-facing only
• expo-local-authentication for biometric lock screen
• Per-item API endpoints (not bulk) for all mutations

Shared Code with Web

Not shared: UI components, routing, auth flows, storage — all platform-specific. The mobile app does not use @leadmetrics/ui (DOM-based React components).

Build & Distribution

Android emulator setup (dev):

• JDK 17, Android SDK, AVD with snapshot boot enabled
• API host: 10.0.2.2 (Android emulator maps to machine’s localhost)
• MSYS path fix required on Windows for Metro
• UIAutomator coordinates used for login in automated tests

Metro: restart Metro before emulator login after dependency changes.

Testing

No Playwright E2E for mobile — manual testing + UIAutomator for emulator automation.

Error Monitoring

Build-Time Configuration

Mobile apps do not use .env files. Config is injected via expo-constants at build time and via Expo’s app.config.js / EAS environment variables.

import Constants from "expo-constants";
const API_URL = Constants.expoConfig?.extra?.apiUrl ?? "http://10.0.2.2:3003";

Key build variables:

API_URL=https://api.leadmetrics.io
APP_ENV=development | staging | production
GOOGLE_SERVICES_FILE=         # google-services.json path for FCM (Android)
SENTRY_DSN=                   # production only

Secrets never enter the mobile bundle — all sensitive operations go through the Fastify API.