jukebox/QUICK_START.md

🎵 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

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

Development

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

// 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

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