jukebox/MOBILE_APP_EXPLORATION.md

Jukebox Project - Mobile App Exploration Report

📱 PROJECT OVERVIEW

Project Type: React Native Mobile App + Web Admin Panel + Laravel API Backend Current Date: May 12, 2026 Repository Location: /home/mathias/jukebox

---

🏗️ ARCHITECTURE OVERVIEW

jukebox/
├── jukebox/                    # React Native Mobile App (Expo)
│   ├── admin_panel/           # Web-based Admin Panel (React + Vite)
│   └── src/                   # Mobile app source code
├── www/api/                   # Laravel REST API Backend (PHP)
├── db/                        # Database schema and scripts
├── mocks/                     # UI mockups and design files
└── flyer/                     # Marketing materials

---

📲 MOBILE APP (REACT NATIVE / EXPO)

Technology Stack

• Framework: React Native 0.81.5 with Expo 54.0.33
• Navigation: React Navigation Native (Stack Navigator)
• State Management: React Context API (LibraryProvider, PlayerProvider)
• UI Components: React Native core components
• Icons: Expo Vector Icons, React Native Vector Icons
• Animation: React Native Reanimated
• Styling: StyleSheet (React Native native styling)
• Special Libraries:
  • rn-inkpad (UI components - buttons, sliders)
  • expo-linear-gradient (gradient backgrounds)
  • react-native-safe-area-context (safe area handling)

Project Configuration

{
  "name": "jukebox",
  "version": "1.0.0",
  "platforms": ["iOS", "Android", "Web"],
  "orientation": "portrait",
  "newArchEnabled": true
}

Scripts

• npm start - Start Expo development server
• npm run android - Run on Android emulator/device
• npm run ios - Run on iOS simulator/device
• npm run web - Run in web browser

---

🎯 MOBILE APP SCREENS

1. HomeScreen (src/screens/HomeScreen.js)

• Purpose: Main landing page / music library browse
• Features:
  • Header with navigation icons (Profile, Settings)
  • "Liked tracks" section (top 5 tracks with shortcut)
  • Albums grid (2 columns)
  • Tap on album to navigate to AlbumScreen
  • Tap on liked track to navigate to album
• Data Source: Uses LibraryContext (mock data)
• Navigation: navigation.navigate("Album", { album })

2. AlbumScreen (src/screens/AlbumScreen.js)

• Purpose: Display album details and track list
• Features:
  • Album cover image (140x140)
  • Album title, artist, release date, label, duration
  • FlatList of all tracks in album
  • Heart icon to like/unlike tracks
  • Back button to return to HomeScreen
• Data Source: LibraryContext (albums state)
• Navigation: Can navigate back to home

3. LikedTracksScreen (src/screens/LikedTracksScreen.js)

• Purpose: View all liked tracks with search and filtering
• Features:
  • Search input to filter by title/artist
  • Sort menu with 3 options: Date Added, Name, Length
  • Sort direction toggle (ASC/DESC)
  • FlatList of liked tracks
  • Can navigate to album from track
• Data Source: LibraryContext (computed likedTracks)
• Navigation: Back button, navigate to Album

4. LoginScreen (src/screens/LoginScreen.js)

• Purpose: User authentication
• Features:
  • Email input field
  • Password input field (secured)
  • "Log In" button
  • "Reset password" link
  • "Sign Up" link
• State: Local component state (email, password)
• Action: onLogin() - currently just logs to console
• Navigation: Can navigate to PasswordReset, SignUp, back

5. SignUpScreen (src/screens/SignUpScreen.js)

• Purpose: User registration
• Features:
  • Email input
  • Password input
  • Confirm password input
  • "Sign Up" button
• State: Local component state
• Action: onSignUp() - currently just logs to console
• Navigation: Back button

6. PasswordResetScreen (src/screens/PasswordResetScreen.js)

• Purpose: Password recovery
• Features:
  • Email input for account recovery
  • "Send email" button
• Action: onResetButtonPress() - currently just logs to console
• Navigation: Back button

7. SettingsScreen (src/screens/SettingsScreen.js)

• Purpose: User preferences and account management
• Features:
  • Toggle: Enable notifications (default: true)
  • Toggle: High quality streaming (default: false)
  • "Log out" button (red)
• State: Local component state (notificationsEnabled, highQuality)
• Navigation: Back button

---

🧩 COMPONENTS

1. Header (src/components/Header.js)

• Displays screen title
• Optional action icons (Profile, Settings)
• Used on: HomeScreen, LikedTracksScreen, LoginScreen, SettingsScreen, etc.
• Props: title (string), showIcons (boolean)

2. TrackRow (src/components/TrackRow.js)

• Displays single track in a list item format
• Shows: Cover image (46x46), title, artist, duration, heart icon
• Props: title, artist, duration, cover, liked, onToggleLike, onPress
• Used in: HomeScreen, AlbumScreen, LikedTracksScreen

3. MediaPlayer (src/components/MediaPlayer.js)

• Floating player widget at bottom of screen
• Shows: Track name/artist, progress bar with times, play/pause button
• Uses: rn-inkpad Slider and Button components
• Uses: expo-linear-gradient for dark gradient background
• State: isPlaying, progress (local component state)
• Note: Currently shows placeholder data, not connected to actual playback
• Position: Absolute bottom-right, z-index: 999

4. DurationFormatter (src/components/DurationFormatter.js)

• Utility function to format seconds to MM:SS or HH:MM:SS format
• Export: durationFormatter(totalSeconds)
• Used in: TrackRow, AlbumScreen, LikedTracksScreen

---

🎵 DATA MANAGEMENT

Data Flow Architecture

LibraryContext (Global State)
├── albums: Array of album objects
├── likedTracks: Computed memoized array
├── toggleLike(albumId, trackId): Function
└── [Components access via useLibrary() hook]

LibraryContext (src/contexts/LibraryContext.js)

• State: albums from initialLibrary (mock data)
• Methods:
  • toggleLike(albumId, trackId) - Toggles liked status of a track
  • Computed likedTracks - Memoized array of all liked tracks across albums
• Usage: const { albums, likedTracks, toggleLike } = useLibrary()

Mock Data (src/data/library.js)

Currently Using STATIC MOCK DATA - No API integration yet!

Data structure:

[
  {
    id: 'album1',
    title: 'Album Title',
    artist: 'Artist Name',
    date: 'YYYY-MM-DD',
    label: 'Label Name',
    duration: 8485 (in seconds),
    cover: require('../../assets/covers/cover.jpg'),
    tracks: [
      {
        id: 'a1t1',
        title: 'Track Title',
        duration: 183,
        liked: false
      },
      // ... more tracks
    ]
  },
  // ... more albums
]

Current Mock Data:

• 2 albums (Swans - "Soundtracks For The Blind", Daft Punk - "Discovery")
• 26 + 14 = 40 total tracks
• Some tracks pre-marked as liked

---

🎛️ STATE MANAGEMENT

PlayerProvider Context (App.js)

{
  currentTrack: Track object or undefined,
  setCurrentTrack: Function,
  isPlaying: boolean,
  setIsPlaying: Function
}

• Provides player state globally
• Used by MediaPlayer component and navigation
• Status: Provider setup exists, but MediaPlayer doesn't actually use currentTrack

LibraryProvider Context

• See above - manages album library and likes

---

📱 NAVIGATION STRUCTURE

Stack Navigator Screens (in order)

1. Home
2. LikedTracks
3. Album
4. SignUp
5. Login
6. PasswordReset
7. Settings

Navigation Type: React Navigation Native Stack

• Pattern: Screen name → Component mapping
• Style: Header hidden (headerShown: false)
• Safe Area: Wrapped with SafeAreaProvider

---

🖼️ UI/UX DETAILS

Color Scheme

• Primary Background: #000 (pure black)
• Secondary Background: #111827, #1f2937 (dark grays)
• Text Primary: #fff (white)
• Text Secondary: #9ca3af (light gray)
• Text Meta: #cfcfcf (medium gray)
• Accent (Like): #ff4d6d (pink/red)
• Accent (Buttons): #dbdbdb (light gray)
• Warning/Danger: #e36d6d (red)

Layout

• Portrait only orientation
• Safe area respecting
• Padding: typically 16px horizontal, 24px vertical
• Border radius: typically 8-10px
• Shadow/Elevation handling for media player (elevation: 10)

---

🌐 WEB ADMIN PANEL

Technology Stack

• Framework: React 19.2.0
• Build Tool: Vite 7.3.1
• Routing: React Router DOM 7.13.1
• Styling: Tailwind CSS 4.0.0
• State Management: React Context (AuthContext)

Admin Panel Structure

admin_panel/
├── src/
│   ├── App.jsx              # Main router and layout
│   ├── main.jsx             # Entry point
│   ├── pages/
│   │   ├── LoginPage.jsx    # Admin login
│   │   ├── AlbumsPage.jsx   # Album management
│   │   ├── AlbumTracksPage.jsx  # Track management
│   │   └── UsersPage.jsx    # User management
│   ├── contexts/
│   │   └── AuthContext.jsx  # Authentication state
│   └── services/
│       └── api.js           # API client
├── vite.config.js
├── eslint.config.js
└── package.json

Admin Pages

LoginPage

• Email/password form
• Connects to /api/login
• Stores token in localStorage
• Redirects on success

AlbumsPage

• List all albums
• Create, edit, delete albums
• Upload album cover images
• Navigate to AlbumTracksPage for track management

AlbumTracksPage (/albums/:albumId/tracks)

• Manage tracks within an album
• Add, edit, delete tracks
• Upload audio files
• Reorder tracks

UsersPage

• List all users
• View user details
• Edit user roles
• Delete users

Admin API Integration (services/api.js)

const api = {
  // Albums
  getAlbums(),
  getAlbumById(id),
  addAlbum(data),
  updateAlbum(id, data),
  deleteAlbum(id),
  
  // Tracks
  addTrack(data),
  updateTrack(id, data),
  deleteTrack(id),
  reorderTracks(albumId, positions),
  
  // Artists
  getArtists(),
  addArtist(data),
  
  // Genres
  getGenres(),
  addGenre(data),
  
  // File uploads
  uploadImage(file),
  uploadAudio(file),
  
  // Users
  getUsers(),
  updateUser(id, data),
  deleteUser(id)
}

---

🔌 BACKEND API (LARAVEL)

API Base URL

• Local Development: http://localhost/api
• Environment Variable: VITE_API_URL

Authentication

• Method: Laravel Sanctum (Bearer Token)
• Token Storage: localStorage (token key)
• Expires On: 401 Unauthorized → clears localStorage & redirects to /login

Authentication Endpoints

POST   /register              - Create new user (user role)
POST   /login                 - Login & get token
POST   /logout                - Logout & invalidate token
GET    /me                    - Get current user info

Database Models (from API_QUICK_REFERENCE.md)

Users
├─ has_many: Tracks (likes table)
├─ belongs_to: Role

Albums
├─ belongs_to: Label
├─ has_many: Tracks

Tracks
├─ belongs_to: Album
├─ belongs_to_many: Artists (artist_track)
├─ belongs_to_many: Genres (track_genre)
├─ belongs_to_many: Users (likes)

Artists
├─ belongs_to: Label
├─ belongs_to_many: Tracks

Genres
└─ belongs_to_many: Tracks

Labels
├─ has_many: Artists
└─ has_many: Albums

Roles
└─ has_many: Users

Key API Endpoints (for mobile)

GET    /albums               - Get all albums
GET    /albums/{id}          - Get album with tracks
GET    /tracks               - Get all tracks
GET    /tracks/{id}          - Get track details
POST   /tracks/{id}/like     - Like a track
DELETE /tracks/{id}/like     - Unlike a track
GET    /me/likes             - Get liked tracks
GET    /artists              - Get artists
GET    /genres               - Get genres

Admin-Only Endpoints

POST/PUT/DELETE /albums
POST/PUT/DELETE /tracks
POST/PUT/DELETE /artists
POST/PUT/DELETE /genres
POST/PUT/DELETE /labels
POST/PUT/DELETE /users

---

🚨 CURRENT STATE & LIMITATIONS

✅ What's Implemented

1. ✅ Complete navigation structure (all screens)
2. ✅ Mock data with 2 sample albums
3. ✅ Like/unlike functionality (local state)
4. ✅ Search and sort in LikedTracksScreen
5. ✅ MediaPlayer UI component (visual only)
6. ✅ Context API setup for global state
7. ✅ SafeAreaProvider for device compatibility
8. ✅ Admin panel basic UI structure
9. ✅ API client with authentication headers
10. ✅ Tailwind CSS styling in admin

❌ What's NOT Implemented

1. ❌ No API Integration - Mobile app still uses mock data
2. ❌ No Real Authentication - Login/SignUp don't call API
3. ❌ No Audio Playback - MediaPlayer is UI-only, no actual playback
4. ❌ No Real Settings - Settings switches don't persist or affect app
5. ❌ No Password Reset - Password reset logic not implemented
6. ❌ No Data Persistence - App state lost on refresh
7. ❌ No Image Assets - Need to verify album covers exist
8. ❌ No Admin Page Implementations - AlbumsPage, UsersPage, etc. are stubs
9. ❌ No File Upload - Upload endpoints not integrated in admin
10. ❌ No Error Handling - Limited error boundaries or error messages
11. ❌ No Loading States - No spinners or loading indicators
12. ❌ No Pagination - API has no pagination, all records returned

🔄 Backend API Status

• ✅ Built with Laravel
• ✅ Authentication system ready (Sanctum)
• ✅ Database schema designed
• ✅ Most controllers implemented
• ⚠️ Limited test coverage
• ⚠️ No CORS configuration file
• ⚠️ No pagination or filtering
• ⚠️ No API documentation (though quick reference exists)

---

📊 DATA FLOW SUMMARY

Current Flow (Mock Data)

App.js
├── PlayerProvider
│   └── LibraryProvider
│       ├── initialLibrary (mock data)
│       └── [All Screens]
│           ├── HomeScreen
│           ├── AlbumScreen
│           ├── LikedTracksScreen
│           └── LoginScreen (not connected)

Expected Future Flow (With API)

API (Laravel)
├── /albums
├── /tracks
├── /users/me/likes
└── /login
    ↓
LibraryContext (should fetch from API)
├── albums
├── likedTracks
└── currentUser
    ↓
All Screens display live API data

---

🛠️ NEXT STEPS FOR INTEGRATION

1. Connect Mobile App to API

   • Replace initialLibrary with API calls in LibraryProvider
   • Implement login/logout with real authentication
   • Add data persistence (localStorage or AsyncStorage)

2. Implement Audio Playback

   • Use expo-av for audio playback
   • Connect MediaPlayer to PlayerProvider
   • Stream tracks from API

3. Build Admin Panel Pages

   • Implement AlbumsPage.jsx
   • Implement UsersPage.jsx
   • Implement AlbumTracksPage.jsx

4. Add Error Handling

   • API error boundaries
   • User feedback (toasts/alerts)
   • Retry logic

5. Performance Optimizations

   • Add pagination to API
   • Implement image caching
   • Add loading states
   • Memoize expensive computations

---

📁 FILE SUMMARY

/home/mathias/jukebox/jukebox/
├── App.js (100 lines) - Root component, navigation, contexts
├── index.js (9 lines) - Expo entry point
├── app.json - Expo configuration
├── package.json - Dependencies
├── src/
│   ├── screens/ (6 files, ~100-150 lines each)
│   │   ├── HomeScreen.js
│   │   ├── AlbumScreen.js
│   │   ├── LikedTracksScreen.js
│   │   ├── LoginScreen.js
│   │   ├── SignUpScreen.js
│   │   ├── PasswordResetScreen.js
│   │   └── SettingsScreen.js
│   ├── components/ (4 files)
│   │   ├── Header.js
│   │   ├── TrackRow.js
│   │   ├── MediaPlayer.js
│   │   └── DurationFormatter.js
│   ├── contexts/ (1 file)
│   │   └── LibraryContext.js
│   ├── data/ (1 file)
│   │   └── library.js (mock data)
│   └── .expo/
├── assets/
│   ├── covers/ (album cover images)
│   ├── icon.png
│   ├── splash-icon.png
│   ├── adaptive-icon.png
│   └── favicon.png
└── admin_panel/
    ├── src/ (7 files)
    └── package.json

/home/mathias/jukebox/www/api/ (Laravel)
├── app/
│   ├── Http/Controllers/
│   ├── Models/
│   └── Providers/
├── routes/api.php
├── database/
│   ├── migrations/
│   └── seeders/
└── config/

Total: ~1000+ lines of React Native code
        ~500+ lines of React admin code
        ~2000+ lines of Laravel PHP code

---

🎯 KEY FINDINGS

1. Mobile App: Well-structured React Native project using Expo with clear separation of concerns (screens, components, contexts)

2. State Management: Uses React Context API - simple but sufficient for current size; could upgrade to Redux/Zustand if needed

3. Design Consistency: Dark theme throughout with consistent color palette and spacing

4. Backend Ready: Laravel API is built but mobile app hasn't been connected yet

5. No Real Data Persistence: Everything is in-memory state; needs localStorage/AsyncStorage or API integration

6. Admin Panel: Basic structure exists but needs implementation of actual pages

7. Authentication Flow: Designed but not implemented end-to-end

---

Report Generated: May 12, 2026 Explorer: Claude Code Status: Ready for development phase