AlphaMind Mobile Frontend

Overview

The mobile-frontend directory contains the React Native mobile application for AlphaMind, providing traders with on-the-go access to portfolio monitoring, alerts, and trading capabilities. This cross-platform mobile application delivers a responsive and intuitive interface for monitoring investments and executing trades from any mobile device.

Features

The mobile application provides the following key features:

• Authentication: Complete login and registration system with JWT token management
• Portfolio Monitoring: Real-time tracking of portfolio performance with KPI cards
• Dashboard: Visual analytics and performance metrics with refresh capability
• Research Access: Browse and access research papers and publications
• Settings Management: Theme preferences, notification settings, and user profile
• State Management: Redux Toolkit for centralized state management
• Offline Support: Mock data mode for development without backend
• API Integration: Axios-based API client with interceptors for authentication

Design System and Navigation

The mobile app shares the web frontend's "Quant Terminal" design language: an indigo brand with a cyan accent, color-coded positive and negative deltas, and a first-class light and dark mode driven by the in-app theme preference (System, Light, or Dark) from Settings.

Navigation flow:

1. Unauthenticated users start on a Landing screen, then proceed to Sign In or Create an Account.
2. Authenticated users see a bottom tab bar: Home (dashboard), Strategies, Portfolio, Risk, and More. The More tab links to Research, Documentation, About, and Settings.

Technology Stack

• Framework: React Native (Expo)
• State Management: Redux Toolkit
• Navigation: React Navigation (Bottom Tabs, Native Stack)
• UI Components: React Native Paper (Material Design 3)
• Charts: Victory Native, React Native Chart Kit
• API Client: Axios
• Testing: Jest, React Native Testing Library
• Code Quality: ESLint, Prettier

Directory Structure

mobile-frontend/
├── __tests__/                 # Test files
│   ├── components/           # Component tests
│   ├── screens/              # Screen tests
│   ├── services/             # Service tests
│   ├── store/                # Redux tests
│   └── integration/          # Integration tests
├── assets/                    # Static assets (images, fonts)
├── components/                # Reusable UI components
│   ├── ErrorMessage.js
│   ├── KPICard.js
│   └── LoadingSpinner.js
├── constants/                 # Application constants
│   ├── config.js             # API and app configuration
│   └── theme.js              # Theme definitions
├── hooks/                     # Custom React hooks
├── navigation/                # Navigation configuration
│   ├── AppNavigator.js       # Main app navigator
│   └── AuthNavigator.js      # Authentication navigator
├── screens/                   # Screen components
│   ├── DocumentationScreen.js
│   ├── FeaturesScreen.js
│   ├── HomeScreen.js
│   ├── LoginScreen.js
│   ├── RegisterScreen.js
│   ├── ResearchScreen.js
│   └── SettingsScreen.js
├── services/                  # API and external services
│   ├── api.js                # Axios instance with interceptors
│   ├── authService.js        # Authentication API
│   ├── portfolioService.js   # Portfolio API
│   └── researchService.js    # Research API
├── store/                     # Redux store
│   ├── index.js              # Store configuration
│   └── slices/               # Redux slices
│       ├── authSlice.js
│       ├── portfolioSlice.js
│       └── settingsSlice.js
├── utils/                     # Utility functions
├── App.js                     # Root component
├── index.js                   # App entry point
├── app.json                   # Expo configuration
├── babel.config.js            # Babel configuration
├── jest.config.js             # Jest configuration
├── jest.setup.js              # Jest setup file
├── package.json               # Dependencies and scripts
├── .env.example               # Environment variables template
└── .env                       # Environment variables (create from .env.example)

Getting Started

Prerequisites

• Node.js 16+
• npm or yarn
• Expo CLI
• iOS Simulator (macOS) or Android Emulator/Device

Installation

1. Navigate to the mobile-frontend directory:

   cd mobile-frontend

2. Install dependencies:

   npm install

3. Create environment file:

   cp .env.example .env

   Edit .env to configure your settings:

   • Set API_BASE_URL to your backend URL (default: http://localhost:5000)
   • Set ENABLE_MOCK_DATA=true for offline development

Running the Application

Development Mode

Start the Expo development server:

npm start

This will open the Expo DevTools in your browser. From there, you can:

• Press i to open iOS Simulator
• Press a to open Android Emulator
• Scan QR code with Expo Go app on your phone

Run on Specific Platform

# iOS
npm run ios

# Android
npm run android

# Web
npm run web

Backend Integration

The mobile app integrates with the AlphaMind backend API.

Running with Backend

1. Start the backend server (from repository root):

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   python src/main.py

   The backend should start on http://localhost:5000

2. Configure mobile app to connect to backend:

   • Edit .env and set ENABLE_MOCK_DATA=false
   • Set API_BASE_URL=http://localhost:5000 (or your backend URL)
   • For physical devices, use your computer's IP address instead of localhost

3. Start mobile app:

   npm start

Running without Backend (Mock Data)

For development without backend:

• Set ENABLE_MOCK_DATA=true in .env
• The app will use mock data from services (portfolioService, researchService)

Testing

Run Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run specific test
npm test -- --testPathPattern="authService"

Test Coverage

Current test suites:

• ✅ Authentication service tests
• ✅ Redux store slice tests
• ✅ Configuration tests
• ✅ API integration tests

Code Quality

Linting

# Check for linting errors
npm run lint

# Auto-fix linting errors
npm run lint:fix

Formatting

# Check code formatting
npm run format:check

# Auto-format code
npm run format

Configuration

Environment Variables

Create a .env file based on .env.example:

# API Configuration
API_BASE_URL=http://localhost:5000
API_TIMEOUT=30000

# Feature Flags
ENABLE_MOCK_DATA=false        # Use mock data instead of API
ENABLE_OFFLINE_MODE=true      # Enable offline capabilities

# Environment
NODE_ENV=development

Theme Customization

Themes are defined in constants/theme.js. You can customize:

• Light theme colors
• Dark theme colors
• Component-specific styling

Users can switch themes in Settings screen.

Key Features Implementation

Authentication

• JWT token-based authentication
• Login and registration screens
• Auto-login with stored credentials
• Token refresh handling
• Secure token storage with AsyncStorage

State Management

• Redux Toolkit for centralized state
• Async thunks for API calls
• Slices for auth, portfolio, and settings
• Persistent state with AsyncStorage

API Integration

• Axios client with interceptors
• Automatic token injection
• Error handling and retry logic
• Mock data support for offline development

Navigation

• Tab-based navigation for main screens
• Stack navigation for authentication flow
• Protected routes requiring authentication
• Deep linking support

Building for Production

Android

# Generate APK
expo build:android

# Or using EAS Build (recommended)
eas build --platform android

iOS

# Generate IPA
expo build:ios

# Or using EAS Build (recommended)
eas build --platform ios

Troubleshooting

Common Issues

1. Metro bundler cache issues:

   expo start -c

2. Node modules issues:

   rm -rf node_modules
   npm install

3. iOS Simulator not opening:

   # Ensure Xcode is installed
   xcode-select --install

4. Android Emulator issues:

   • Ensure Android Studio is installed
   • Create an AVD (Android Virtual Device)
   • Start emulator before running npm run android

5. Backend connection issues:

   • Check backend is running on correct port
   • For physical devices, use computer's IP instead of localhost
   • Check firewall settings

Performance Optimization

• Redux state normalized and optimized
• Memoized selectors and components
• Lazy loading for heavy screens
• Image optimization with caching
• Pull-to-refresh for data updates

Accessibility

• Semantic labeling for screen readers
• Sufficient color contrast
• Touch target sizes (minimum 44x44)
• Keyboard navigation support

Security

• Secure token storage with AsyncStorage
• No sensitive data in Redux state
• HTTPS enforcement for API calls
• Token expiration handling
• Input validation and sanitization