# 🎵 Jukebox Mobile App - Quick Start Guide

## Project Structure at a Glance

```
jukebox/
├── 📱 jukebox/              # React Native Mobile App (Expo)
│   ├── src/
│   │   ├── screens/         # 7 screens (Home, Album, LikedTracks, Auth)
│   │   ├── components/      # Reusable UI components
│   │   ├── contexts/        # State management (Library, Player)
│   │   └── data/            # Mock data (currently hardcoded)
│   ├── admin_panel/         # React web admin dashboard
│   └── assets/              # Images and icons
├── 🔌 www/api/              # Laravel REST API backend
├── 📋 db/                   # Database schema
└── 📐 mocks/                # UI mockups and designs
```

---

## 🚀 Running the Mobile App

### Prerequisites
```bash
# Install Node.js 18+ and npm
# Install Expo CLI globally
npm install -g expo-cli
```

### Development
```bash
cd /home/mathias/jukebox/jukebox

# Start development server
npm start

# Or run on specific platform
npm run android    # Android emulator
npm run ios        # iOS simulator  
npm run web        # Web browser
```

### What Works ✅
- Navigation between all screens
- Like/unlike tracks
- Search and sort in liked tracks
- UI layouts and styling
- Header and components

### What's Missing ❌
- **API Integration** - Still uses hardcoded mock data
- **Audio Playback** - No actual music playing
- **Authentication** - Login doesn't connect to backend
- **Data Persistence** - State resets on app close

---

## 📊 Current Data (Mock)

**2 Albums in app.data.library:**
1. **Soundtracks For The Blind** by Swans (1996)
   - 26 tracks
   - 8485 seconds total

2. **Discovery** by Daft Punk (2001)
   - 14 tracks  
   - 3650 seconds total

**Total**: 40 tracks, some marked as liked

---

## 🎯 Screen Map

| Screen | Location | Purpose | Status |
|--------|----------|---------|--------|
| **Home** | HomeScreen.js | Browse albums, see liked tracks | ✅ Working |
| **Album** | AlbumScreen.js | View album details and track list | ✅ Working |
| **Liked Tracks** | LikedTracksScreen.js | Search/sort liked tracks | ✅ Working |
| **Login** | LoginScreen.js | User authentication | ⚠️ UI only |
| **Sign Up** | SignUpScreen.js | User registration | ⚠️ UI only |
| **Password Reset** | PasswordResetScreen.js | Recovery flow | ⚠️ UI only |
| **Settings** | SettingsScreen.js | User preferences | ⚠️ UI only |

---

## 🔑 Key Files to Understand

### State Management
- **`src/contexts/LibraryContext.js`** - Album library and likes state
- **`App.js`** - PlayerProvider (music player state)

### Data
- **`src/data/library.js`** - All mock data lives here

### Main Components
- **`src/components/TrackRow.js`** - Single track display
- **`src/components/MediaPlayer.js`** - Bottom player widget
- **`src/components/Header.js`** - Screen headers

---

## 🔌 API Status

Backend is built at `www/api/` but mobile app isn't connected yet.

**Key Endpoints Available** (not yet used by mobile):
```
POST   /api/login              # User login
GET    /api/albums             # Get all albums
GET    /api/albums/{id}        # Get album with tracks
POST   /api/tracks/{id}/like   # Like a track
GET    /api/me/likes           # Get user's liked tracks
```

---

## 🛠️ Next Development Priorities

### Priority 1: Connect to API
```javascript
// In LibraryContext.js, replace:
const [albums, setAlbums] = useState(initialLibrary);

// With:
useEffect(() => {
  fetch('/api/albums')
    .then(r => r.json())
    .then(data => setAlbums(data));
}, []);
```

### Priority 2: Add Audio Playback
```bash
npm install expo-av
```

### Priority 3: Implement Authentication
- Connect LoginScreen to `/api/login`
- Store token in AsyncStorage
- Fetch user's liked tracks after login

### Priority 4: Admin Panel Pages
Implement the stub pages in `admin_panel/src/pages/`

---

## 📱 Screen Navigation Flow

```
Home Screen
├─ Click Album → Album Screen
│  └─ Track → Like/Unlike
├─ Liked Tracks ➚ → Liked Tracks Screen
│  ├─ Search & Filter
│  └─ Sort by Name/Date/Length
├─ User Icon → Login Screen
│  ├─ Don't have account? → Sign Up Screen
│  └─ Forgot password? → Password Reset Screen
└─ Settings Icon → Settings Screen
   └─ Notifications & Audio Quality toggles
```

---

## 🎨 Design System

### Colors
- **Background**: Pure black (`#000`)
- **Surfaces**: Dark gray (`#111827`, `#1f2937`)
- **Text**: White (`#fff`)
- **Accent**: Pink/Red (`#ff4d6d` for likes)
- **Buttons**: Light gray (`#dbdbdb`)

### Spacing
- **Container padding**: 16px horizontal
- **Vertical spacing**: 12-24px
- **Border radius**: 8-10px

### Typography
- **Headers**: Bold, 24-32px
- **Body**: Regular, 15-16px
- **Meta**: Gray, 12-14px

---

## 🧪 Testing the App

### Test the Like Feature
1. Open HomeScreen
2. Find a track in "Liked tracks" section
3. Click the heart icon
4. Scroll to Liked Tracks Screen to verify

### Test Search & Sort
1. Navigate to "Liked Tracks ➚"
2. Type in search box (searches title/artist)
3. Click "Sort by" dropdown
4. Try sorting by: Date Added, Name, Length
5. Click ASC/DESC to reverse order

### Test Navigation
1. From Home → click any album
2. Album Screen → click back button
3. Verify you return to Home

---

## 🐛 Known Issues

1. **MediaPlayer doesn't actually play music** - It's just a UI component
2. **Login form doesn't save user data** - No backend integration
3. **Settings toggles don't persist** - No AsyncStorage usage
4. **No error handling** - API calls will fail silently
5. **No loading indicators** - Data fetching appears instant but might lag

---

## 📚 Further Reading

- **Full Exploration**: `MOBILE_APP_EXPLORATION.md`
- **API Docs**: `www/api/API_QUICK_REFERENCE.md`
- **React Navigation**: https://reactnavigation.org/docs/native-stack-navigator/
- **Expo Docs**: https://docs.expo.dev/

---

## 💡 Tips for Development

1. **Hot reload**: Press `r` in terminal while `npm start` runs
2. **Inspect state**: Use React DevTools browser extension
3. **Test on real device**: Use Expo Go app and scan QR code
4. **Debug API**: Use the Postman collection: `jukebox-api.postman_collection.json`
5. **Check data structure**: Look at `src/data/library.js` first

---

**Last Updated**: May 12, 2026
**Explorer**: Claude Code