# Lilith Mobile App - React Native Development Environment

## Overview

Lilith Mobile is a comprehensive React Native application for AI wisdom platform featuring chat, meditation, and learning capabilities. This document outlines the development environment setup and workflow.

## 🚀 Quick Start

### Prerequisites

- Node.js 18+
- Android SDK (installed)
- Java 11+
- React Native CLI

### Environment Setup

```bash
# Clone and navigate to mobile directory
cd mobile

# Setup development environment
source scripts/setup-dev-env.sh

# Install dependencies
npm install --legacy-peer-deps

# Start Metro bundler
npm start
```

### Development Workflow

Use the provided development workflow script:

```bash
# Setup environment
./scripts/dev-workflow.sh setup

# Run tests
./scripts/dev-workflow.sh test

# Start Metro bundler
./scripts/dev-workflow.sh metro

# Run on Android
./scripts/dev-workflow.sh android

# Lint code
./scripts/dev-workflow.sh lint
```

## 📱 Application Architecture

### Core Features

- **AI Chat Interface**: Real-time conversations with AI mentors
- **Voice Input/Output**: Speech recognition and TTS capabilities
- **Meditation & Audio**: Guided meditation with audio controls
- **Offline Support**: Local data persistence and sync
- **Push Notifications**: Smart scheduling and delivery
- **Biometric Authentication**: Secure login with fingerprint/face ID

### Technology Stack

- **React Native 0.73.2**: Cross-platform mobile framework
- **TypeScript**: Type-safe development
- **Zustand**: State management
- **React Navigation**: Navigation and routing
- **AsyncStorage**: Local data persistence
- **React Native Track Player**: Audio playback
- **React Native Voice**: Speech recognition
- **Push Notifications**: Local and remote notifications

## 🧪 Testing

### Test Suite Status

- **NotificationScheduler**: 24/31 tests passing (77% pass rate)
- **Comprehensive test coverage** for core services
- **Jest configuration** optimized for React Native
- **Mock setup** for native modules

### Running Tests

```bash
# Run all tests
npm test

# Run specific test suite
npm test -- --testNamePattern="NotificationScheduler"

# Run with coverage
npm test -- --coverage
```

### Test Infrastructure

- **Jest Setup**: Configured in `jest.config.js`
- **Mock Configuration**: Comprehensive mocking in `jest.setup.js`
- **React Native Testing Library**: Component testing
- **Async Storage Mocking**: Storage testing support

## 🔧 Development Tools

### Metro Bundler

The Metro bundler is configured and running on port 8081:

```bash
# Start with cache reset
npx react-native start --reset-cache

# Check status
curl http://localhost:8081/status
```

### Android Development

Android SDK and build tools are configured:

- **Android SDK**: `/home/ubuntu/Android/sdk`
- **Build Tools**: 34.0.0
- **Platform**: Android 33/34
- **Java Home**: `/usr/lib/jvm/java-11-openjdk-amd64`

### Environment Variables

Key environment variables are automatically configured:

```bash
export ANDROID_HOME="$HOME/Android/sdk"
export PATH="$PATH:$ANDROID_HOME/platform-tools"
export NODE_OPTIONS="--max-old-space-size=4096"
export REACT_NATIVE_METRO_PORT="8081"
```

## 📁 Project Structure

```
mobile/
├── src/
│   ├── components/          # React Native components
│   ├── services/           # Business logic services
│   ├── screens/            # App screens
│   ├── navigation/         # Navigation configuration
│   ├── utils/              # Utility functions
│   └── types/              # TypeScript type definitions
├── __tests__/              # Test files
├── android/                # Android-specific code
├── ios/                    # iOS-specific code (when added)
├── scripts/                # Development scripts
├── jest.config.js          # Jest configuration
├── jest.setup.js           # Test setup and mocks
└── metro.config.js         # Metro bundler configuration
```

## 🎯 Key Services

### ARMeditationService

Immersive native AR meditation orchestration:

- **Tradition-specific overlay bundles** for Zen, Stoic, and Sufi environments with dynamic interactions and animations
- **Spatial audio fields** that place ambient sounds in 3D space with adaptive mixing based on device tracking
- **Session lifecycle management** with automatic cleanup when transitioning between environments
- **State persistence** for overlays and sessions stored via AsyncStorage for quick resume and recovery

### HapticMeditationService

Advanced meditation guidance through multimodal haptics:

- **Guided pattern composer** transforms multi-phase meditation plans into sequenced haptic patterns with tradition-aware cadences (`mobile/src/services/HapticMeditationService.ts`)
- **Adaptive cadence refinement** tunes intensities, frequencies, and amplitudes in response to biofeedback focus areas, coherence, and live breath rate metadata
- **Breathing cadence markers** overlay custom waveforms that mirror pranayama cycles while remaining loop-aware for long-form practices
- **Persistent pattern registry** stores composed guidance flows for reuse alongside existing accessibility and adaptive processing pipelines
- **Full Jest coverage** via `npx jest --config jest.config.js src/__tests__/services/HapticMeditationService.test.ts --runInBand`

### NotificationScheduler

Smart notification scheduling with:

- **Batch processing** for efficiency
- **Quiet hours** respect
- **Rate limiting** to prevent spam
- **Priority-based delivery**
- **Background processing** with retry logic

### Audio Management

Comprehensive audio features:

- **Track Player** integration
- **Voice recording** and playback
- **TTS** (Text-to-Speech) synthesis
- **Background audio** support
- **Audio session** management

### Data Sync

Robust synchronization with:

- **Offline-first** architecture
- **Conflict resolution** engine
- **Background sync** capabilities
- **Data persistence** with AsyncStorage

## 🚨 Current Status

### ✅ Completed

- React Native development environment setup
- Metro bundler configuration and running
- Android SDK installation and configuration
- Development workflow scripts
- Test infrastructure with Jest
- NotificationScheduler service (77% test pass rate)
- Core app structure and components

### 🔄 In Progress

- Test suite improvements (target: 90%+ pass rate)
- Android build configuration refinement
- iOS development environment setup

### 📋 Next Steps

1. Improve test coverage to 90%+
2. Set up iOS development environment
3. Implement Android build pipeline
4. Add end-to-end testing
5. Configure CI/CD for mobile builds

## 🛠️ Troubleshooting

### Common Issues

1. **Metro bundler port conflicts**: Ensure port 8081 is available
2. **Android SDK path**: Verify ANDROID_HOME environment variable
3. **Node memory**: Increase Node.js heap size with NODE_OPTIONS
4. **Test failures**: Check mock configurations in jest.setup.js

### Debug Commands

```bash
# Check Metro status
curl http://localhost:8081/status

# Verify Android SDK
echo $ANDROID_HOME

# Reset Metro cache
npx react-native start --reset-cache

# Clean node modules
rm -rf node_modules && npm install --legacy-peer-deps
```

## 📚 Additional Resources

- [React Native Documentation](https://reactnative.dev/docs/getting-started)
- [React Native CLI](https://github.com/react-native-community/cli)
- [Metro Bundler](https://facebook.github.io/metro/)
- [Jest Testing Framework](https://jestjs.io/)

---

**Last Updated**: October 11, 2025
**Environment**: React Native 0.73.2, Node.js 18+, Android SDK 34