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#
text
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#
- Improve test coverage to 90%+
- Set up iOS development environment
- Implement Android build pipeline
- Add end-to-end testing
- Configure CI/CD for mobile builds
π οΈ Troubleshooting#
Common Issues#
- Metro bundler port conflicts: Ensure port 8081 is available
- Android SDK path: Verify ANDROID_HOME environment variable
- Node memory: Increase Node.js heap size with NODE_OPTIONS
- 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#
Last Updated: October 11, 2025 Environment: React Native 0.73.2, Node.js 18+, Android SDK 34