A comprehensive iOS application built with React Native, featuring full offline support, biometric authentication, push notifications, and advanced audio capabilities.
π Features#
Core Functionality#
- React Native Integration: Cross-platform compatibility with native iOS enhancements
- Offline-First Architecture: Complete offline functionality with intelligent synchronization
- Core Data Persistence: Robust local data storage with automatic conflict resolution
- Background Sync: Seamless synchronization when connectivity is restored
iOS-Specific Features#
- Biometric Authentication: Face ID and Touch ID integration for secure access
- Push Notifications: Rich notification support with custom actions and categories
- Background Audio: Continuous playback of guided meditations and TTS content
- Keychain Storage: Secure storage of sensitive data and authentication tokens
π± Architecture#
Project Structure#
text
ios/
βββ Lilith.xcodeproj/ # Xcode project configuration
βββ Lilith/ # Main application bundle
β βββ AppDelegate.h/.m # Application lifecycle management
β βββ main.m # Application entry point
β βββ Info.plist # Application configuration
β βββ LaunchScreen.storyboard # App launch screen
β βββ Images.xcassets/ # App icons and images
β βββ Managers/ # Native iOS managers
β β βββ LilithCoreDataManager.h/.m # Core Data persistence
β β βββ LilithOfflineSyncManager.h/.m # Background synchronization
β β βββ LilithBiometricManager.h/.m # Biometric authentication
β β βββ LilithNotificationManager.h/.m # Push notifications
β β βββ LilithAudioManager.h/.m # Audio playback and TTS
β βββ DataModel/ # Core Data model definition
β βββ LilithDataModel.xcdatamodeld/Contents
βββ LilithTests/ # Unit and integration tests
βββ Podfile # iOS dependencies
βββ README.md # This documentation
Core Components#
LilithCoreDataManager#
- Purpose: Manages Core Data operations and offline persistence
- Features:
- Multi-context architecture (main + background)
- Automatic migration support
- Cache management and cleanup
- Sync state tracking
LilithOfflineSyncManager#
- Purpose: Handles background synchronization and offline queue management
- Features:
- Network-aware sync scheduling
- Conflict resolution algorithms
- Retry mechanisms with exponential backoff
- Background URL session support
LilithBiometricManager#
- Purpose: Secure biometric authentication and keychain storage
- Features:
- Face ID and Touch ID support
- Secure value storage in keychain
- Authentication timeout management
- Fallback to passcode authentication
LilithNotificationManager#
- Purpose: Rich notification system with intelligent scheduling
- Features:
- Local and push notification handling
- Custom notification categories and actions
- Quiet hours and intelligent delivery
- Badge management and background fetch
LilithAudioManager#
- Purpose: Advanced audio playback and text-to-speech
- Features:
- Background audio session management
- Audio queue and playlist support
- TTS integration with voice selection
- Audio recording capabilities
π οΈ Development Setup#
Prerequisites#
- Xcode 14.0+
- iOS Simulator 12.4+ or physical device
- CocoaPods 1.10+
- Node.js 16+
Installation#
-
Install Dependencies
bashcd ios pod install -
Open Xcode Project
bashopen Lilith.xcworkspace -
Configure Development Team
- Select the Lilith project
- Set your development team in "Signing & Capabilities"
- Update bundle identifier if needed
-
Build and Run
- Select target device/simulator
- Press Cmd+R or click Run button
Development Workflow#
Adding New Features#
- Create native manager in
Lilith/Managers/ - Implement header and implementation files
- Add to AppDelegate integration
- Create unit tests in
LilithTests/ - Update React Native bridge if needed
Testing#
bash
# Run unit tests
xcodebuild test -workspace Lilith.xcworkspace -scheme Lilith -destination 'platform=iOS Simulator,name=iPhone 14'
# Run from Xcode
# Product β Test (Cmd+U)
π Data Model#
Core Data Entities#
Conversation#
id: String (Primary Key)title: Stringpersona: StringcreatedAt: DatelastModified: DateneedsSync: Booleanmessages: Relationship (one-to-many)
Message#
id: String (Primary Key)content: Stringrole: StringcreatedAt: DateneedsSync: Booleanconversation: Relationship (many-to-one)
MeditationSession#
id: String (Primary Key)type: Stringduration: IntegerstartTime: DateuserId: StringneedsSync: Boolean
UserPreferences#
userId: String (Primary Key)preferencesData: Binary (JSON)lastModified: Date
CacheEntity#
key: String (Primary Key)data: BinaryexpiresAt: DatecreatedAt: Date
π§ Configuration#
Audio Session#
objc
// Background playback configuration
[session setCategory:AVAudioSessionCategoryPlayback
mode:AVAudioSessionModeDefault
options:AVAudioSessionCategoryOptionAllowBluetooth |
AVAudioSessionCategoryOptionAllowBluetoothA2DP |
AVAudioSessionCategoryOptionMixWithOthers
error:&error];
Notification Categories#
- MEDITATION_REMINDER: Daily meditation prompts
- DAILY_WISDOM: Inspirational content with share/save actions
- PROGRESS_UPDATE: Achievement notifications
- CHAT_RESPONSE: AI mentor responses with reply actions
Background Modes#
The app supports the following background modes:
- Audio: Continuous media playback
- Background Fetch: Periodic data synchronization
- Remote Notifications: Silent push notifications
- Background Processing: Extended background tasks
π Security Features#
Biometric Authentication#
- Face ID: Secure authentication on supported devices
- Touch ID: Fingerprint authentication on older devices
- Fallback: Device passcode when biometrics fail
- Timeout: Configurable authentication timeout
Keychain Storage#
- Secure: Hardware-backed encryption
- Persistent: Survives app reinstalls
- Shared: Keychain access group configuration
- Compliant: Follows Apple security guidelines
π± Platform Integration#
iOS Specific APIs#
- AVFoundation: Audio playback and recording
- Core Data: Local persistence and relationships
- UserNotifications: Rich notification handling
- LocalAuthentication: Biometric authentication
- CoreLocation: Location-based preferences
- Network Framework: Connectivity monitoring
React Native Bridge#
Native managers are exposed to React Native through custom modules:
javascript
import { NativeModules } from 'react-native';
const { LilithCoreDataManager, LilithAudioManager } = NativeModules;
π¨ Troubleshooting#
Common Issues#
Build Errors#
- Missing Headers: Ensure all
.hfiles are properly imported - Signing Issues: Verify development team and bundle identifier
- Dependency Conflicts: Run
pod updateto resolve version conflicts
Runtime Issues#
- Core Data Migration: Check model version compatibility
- Background Tasks: Verify background modes are enabled
- Audio Session: Ensure proper category configuration
Testing Issues#
- Simulator Limitations: Some features (biometrics) work only on devices
- Network Conditions: Test offline functionality with airplane mode
- Memory Warnings: Monitor for memory leaks in background tasks
Debug Tools#
- Xcode Console: Native log output
- Instruments: Performance and memory analysis
- Core Data Editor: Database inspection tools
- Network Link Conditioner: Poor connectivity testing
π API Reference#
Core Data Manager#
objc
// Create entity
NSManagedObject *conversation = [coreDataManager createEntity:@"Conversation"
inContext:context];
// Fetch entities
NSArray *results = [coreDataManager fetchEntities:@"Message"
predicate:predicate
sortDescriptors:descriptors
inContext:context];
// Save context
[coreDataManager saveContext:context completion:^(NSError *error) {
// Handle save result
}];
Sync Manager#
objc
// Perform background sync
[syncManager performBackgroundSyncWithCompletion:^(BOOL success, NSError *error) {
// Handle sync result
}];
// Cache data offline
[syncManager cacheConversation:conversationData withId:conversationId];
Biometric Manager#
objc
// Authenticate with biometrics
[biometricManager authenticateWithReason:@"Access Lilith"
completion:^(BOOL success, NSError *error, NSString *reason) {
// Handle authentication result
}];
π― Performance Optimization#
Memory Management#
- Use background contexts for data operations
- Implement proper cleanup in dealloc methods
- Monitor for retain cycles with completion blocks
Background Tasks#
- Limit concurrent sync operations
- Implement intelligent retry mechanisms
- Use background URL sessions for large transfers
Battery Life#
- Optimize audio session management
- Use network reachability to avoid unnecessary requests
- Implement proper background task completion
π Testing Strategy#
Unit Tests#
- Core Data operations (CRUD)
- Sync manager logic
- Biometric authentication flow
- Notification scheduling
Integration Tests#
- Offline-to-online workflows
- Background synchronization
- Audio session management
- Push notification handling
UI Tests#
- Authentication flows
- Audio playback controls
- Notification interactions
- Settings management
π Version History#
v1.0.0 (Current)#
- Complete iOS native implementation
- Full offline support with CoreData
- Biometric authentication integration
- Rich notification system
- Background audio playback
- Comprehensive test suite
Development Team: Lilith Mobile Team Last Updated: October 11, 2025 iOS Version: 12.4+ Xcode Version: 14.0+