Psalmodos Mobile Development Guide

This skill provides expert guidance for developing and maintaining Psalmodos Mobile, an Ethiopian Orthodox Christian hymns (mezmurs) streaming app built with Expo and React Native.

Core Architecture Understanding

When working on this project, always consider these fundamental architectural decisions:

Audio Playback System

Player Component Structure

The player has a clear hierarchy:

1. `floating-track-control.tsx` - Mini player (always visible)

2. `mezmur-detail.tsx` - Full-screen player with lyrics

3. `player.tsx` - Main player container containing:

- `PlayerProgressbar.tsx` (seek control)

- `PlayerControls.tsx` (play/pause/skip)

- `PlayerVolumeBar.tsx` (volume control)

Development Instructions

When Adding or Modifying Features

1. **State Management**

- Use Zustand for all state management

- Separate concerns by domain: `mezmur.store.ts` for music, `category.store.ts` for categories

- Implement clear action methods like `togglePlayState()`, `setCurrentMezmur()`

- Ensure reactive updates across all components

2. **Data Flow Pattern**

- Fetch data from Supabase using `fetchMezmurs()`

- Cache in MMKV for offline access

- Add tracks to TrackPlayer queue

- Trigger playback through user interactions

- Synchronize state across all components

3. **Offline-First Implementation**

- Store metadata in MMKV

- Save audio files using FileSystem

- Always check local data first, then fallback to API

- Implement `saveMezmurFile()` for offline playback

- Handle online/offline transitions seamlessly

When Working with Audio Playback

1. **Player State Synchronization**

- Use centralized state in `mezmur.store.ts` as single source of truth

- Ensure mini player and full player stay in sync

- Implement reactive updates for all player components

2. **Background Playback**

- Leverage service-based architecture with TrackPlayer

- Handle remote events through `RNTPService`

- Implement proper cleanup of audio resources

- Ensure battery optimization

3. **Audio Performance**

- Implement efficient buffering strategies

- Manage memory properly with resource cleanup

- Support adaptive quality based on network connection

- Optimize for battery life

When Styling Components

1. Use NativeWind (Tailwind) classes for component styling

2. Reference `constants/tokens.ts` for design system values

3. Define global styles in `global.css`

4. Support automatic light/dark mode theming

5. Ensure cultural sensitivity in design choices for Ethiopian Orthodox traditions

When Organizing Code

Follow this file structure:

When Testing

1. **Component Testing**

- Write unit tests for individual components

- Create integration tests for component interactions

- Implement E2E tests for full user flows

- Test audio playback functionality specifically

2. **Device Testing**

- Test on various iOS versions and iPhone models

- Test on different Android manufacturers and versions

- Test on both low-end and high-end devices

- Test under various network conditions

When Building and Deploying

1. **Development**

- Use Expo Dev Client for custom builds

- Manage environment variables properly

2. **Staging**

- Use EAS Build for preview builds

- Test on real devices before production

3. **Production**

- Use EAS Build for production builds

- Ensure proper code signing for both platforms

- Verify iOS entitlements for background audio

- Implement Android audio focus management for phone calls

- Include appropriate content policies for religious app

- Ensure proper privacy policy and data handling

Key Constraints

1. **Cultural Sensitivity**: Always respect Ethiopian Orthodox traditions and aesthetics

2. **Accessibility**: Design for users of all technical levels

3. **Offline Capability**: Essential feature for areas with poor connectivity

4. **Performance**: Must work smoothly on various device capabilities

5. **Audio Quality**: Maintain high-quality audio playback

6. **Battery Optimization**: Critical for extended listening sessions

Common Patterns

Adding a New Mezmur Feature

1. Define TypeScript interface in `models/`

2. Add actions to `mezmur.store.ts`

3. Create UI components in `components/`

4. Implement offline caching with MMKV

5. Add to TrackPlayer queue management

6. Test on both iOS and Android

Implementing Player Controls

1. Access state from `mezmur.store.ts`

2. Use TrackPlayer methods for playback control

3. Update UI reactively based on state changes

4. Handle background playback scenarios

5. Implement proper error handling

Managing Offline/Online Transitions

1. Check local data availability first

2. Fetch from API if needed and online

3. Update local cache when online

4. Provide clear feedback to user about connection state

5. Handle transitions gracefully without interrupting playback

Success Criteria