Jukebox — Viva Cheat Sheet

1. The big picture (say this as your opener)

"The project has three parts: a React Native mobile app built with Expo, a React + Vite admin panel, and a Laravel REST API backed by a MySQL database. The two front-ends never talk to each other — they each make HTTP requests to the API, which is the single source of truth. The mobile app is the consumer side (browse albums, like tracks); the admin panel is the content-management side (create/edit/delete albums, tracks, users, upload audio and cover art)."

2. Mobile app

"The mobile app is layered. api.js is the only file that knows the server exists — it wraps every fetch call, attaches the Bearer token, and handles 401s. Two React Contexts hold app-wide state: AuthContext for the logged-in user and token (persisted in AsyncStorage), and LibraryContext for albums and liked tracks. Screens consume those contexts through custom hooks (useAuth, useLibrary) and render reusable components like TrackRow. React Navigation handles screen transitions."

Key details:

10.0.2.2 = Android emulator alias for the host machine's localhost (emulator's own localhost is itself, not your PC)
mapAlbum = adapter that translates API field names (cover_path, duration_seconds, nested artists/genres) into the shape the UI expects
likedTrackIds is a Set — O(1) lookup for "is this track liked?"
library.js in src/data/ = dead code, leftover mock data from before the API existed

What's unfinished:

MediaPlayer is a UI mockup — hardcoded text, no audio engine, play button only flips a local boolean
PlayerProvider context exists but nothing ever calls setCurrentTrack
To finish: add expo-av, load tracks.file_path URL, wire tap → setCurrentTrack → player
Mobile has no ProtectedRoute — unauthenticated users aren't redirected to login (unlike the admin panel)

3. The three hooks

Hook	One-liner
`useState`	Gives a component a value that persists across renders; calling the setter updates it and triggers a redraw
`useEffect`	Runs side-effect code (fetch, storage) after render; `[]` = once on mount, `[x]` = re-run when `x` changes
`useContext`	Lets a deeply-nested component read shared state from a Provider above it, skipping prop-drilling

Prop-drilling = the problem Context solves: passing a prop through intermediate components that don't use it just to reach a deep one.

4. Database

"It's a normalized MySQL schema. Reference data (roles, labels, genres) live in their own tables. Core entities are users, albums, artists, tracks. One-to-many relationships use foreign keys on the 'many' side (a track has one album_id; an album has many tracks). Three many-to-many relationships use junction tables — likes (users↔tracks), artist_track, track_genre — each with a composite primary key to prevent duplicates."

Relationship types:

1:N — FK on the many side: tracks.album_id → albums.id
M:N — junction table: likes (user_id, track_id), artist_track, track_genre
Composite PK on likes (user_id, track_id) = a user cannot like the same track twice (enforced at DB level)

ON DELETE rules:

Rule	Where	Why
`RESTRICT`	users → roles	Can't delete a role while users still have it
`SET NULL`	tracks → albums	Delete an album, tracks survive with `album_id = null`
`CASCADE`	all junction tables	A like/link is meaningless without both sides — delete it too

Gotcha: script.sql has no position column on tracks — the file is outdated. The live DB has position; the admin panel sets it and the mobile app sorts by it. Would fix by regenerating script.sql from the live schema.

5. API

"It's a RESTful API built with Laravel resource controllers, so every entity — labels, genres, artists, albums, tracks, users — exposes the standard list/show/create/update/delete routes using GET/POST/PUT/DELETE. Auth uses Laravel Sanctum: register and login are the only public endpoints and return a Bearer token; every other route requires that token in the Authorization header. Two privilege levels: any logged-in user can read the catalog and like tracks; only admins can create/update/delete catalog items or manage users."

Key endpoints:

POST   /login              → { token, user }      (public)
POST   /register           → { token, user }      (public)
GET    /me                 → current user          (auth)
GET    /albums             → album list            (auth)
POST   /tracks             → create track          (admin)
POST   /tracks/{id}/like   → insert likes row      (auth)
DELETE /tracks/{id}/like   → delete likes row      (auth)
GET    /me/likes           → liked tracks list     (auth)
POST   /upload/audio       → save file, return path (admin)

Create track body: { title, file_path, duration_seconds, album_id, artist_ids: [...], genre_ids: [...] } — artist_ids/genre_ids are arrays → server inserts one row per ID into junction tables.

6. Admin panel

"The admin panel is a React + Vite SPA using react-router for navigation. Same architecture as mobile — an AuthContext storing the Sanctum token in localStorage, and an api.js service. Routes are guarded by ProtectedRoute which checks for a token, but real authorization is enforced server-side — the API rejects non-admin tokens with 403. The panel handles full CRUD on albums/tracks plus file uploads for audio and cover art."

Key details:

localStorage (admin) vs AsyncStorage (mobile) — same concept, different platform APIs; localStorage is synchronous so the token can be read directly in useState
Track upload = two API calls: POST /upload/audio (saves file, returns path), then POST /tracks (saves DB row with that path). Binary never touches the DB.
onPickFile creates an in-memory Audio object to auto-read duration from the file's metadata — no manual input needed
isAdmin is computed in AuthContext but never used to block UI — that's intentional: front-end guards are UX, server middleware is the real security
String(user.id).slice(0, 8) is dead code — IDs are integers, not UUIDs

7. End-to-end auth flow

"When a user logs in, the LoginPage calls login() from AuthContext, which POSTs email and password to /api/login. Laravel verifies the password against its bcrypt hash in the DB and returns a Sanctum token plus the user object. The context stores the token in two places — localStorage/AsyncStorage so it survives restarts, and React state so the UI updates. Setting the token in state triggers a cascade: ProtectedRoute unlocks, a useEffect calls /me to re-validate, and on mobile the LibraryProvider's useEffect sees the new token and auto-loads albums and likes. From then on every request attaches the token as a Bearer header — that's how the stateless API authenticates each call and checks the user's role. On startup the stored token is read and /me is called to restore the session; a 401 response wipes storage and redirects to login. Logout revokes the token server-side and clears both storage and state."

Status codes:

401 Unauthorized = bad or missing token ("I don't know who you are")
403 Forbidden = valid token, wrong role ("I know you, but you can't do this")

8. Key vocabulary — drop these terms

Term	Use it when talking about…
Prop-drilling	Why you used Context instead of passing token through every component
Junction table	`likes`, `artist_track`, `track_genre` — how M:N works
Composite primary key	`(user_id, track_id)` on `likes` — prevents duplicate likes
Normalization	Why labels, genres, roles are in their own tables
Bearer token	How every request proves identity to the stateless API
Stateless	Each request is self-contained — server has no memory of prior requests
Laravel Sanctum	The auth package that issues and verifies the tokens
Adapter / mapAlbum	Translates API response shape into UI shape
`expo-av`	The library needed to add real audio playback
ON DELETE CASCADE/RESTRICT/SET NULL	FK behaviour when a parent row is deleted

9. The five things to volunteer before the teacher finds them

library.js in src/data/ is dead code — old mock data, no longer imported
MediaPlayer is a mockup — hardcoded placeholder, no real playback wired up
Mobile has no ProtectedRoute — auth context and API are wired, but screens don't redirect unauthenticated users to login
script.sql is outdated — missing position column on tracks; would regenerate from live DB
getAlbumById in mobile api.js is defined but never called — the app finds albums from the already-loaded list in memory

8.8 KiB Raw Permalink Blame History