241 lines
6.3 KiB
Markdown
241 lines
6.3 KiB
Markdown
# 🎵 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
|