Big commit whatever
This commit is contained in:
+240
@@ -0,0 +1,240 @@
|
||||
# 🎵 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
|
||||
Reference in New Issue
Block a user