How sa1ava/puma works
Project type and purpose
• Project type: Front-end SPA (no backend).
• Purpose: A browser‐based music player that reads a local tracks.json, renders UI controls (play/pause, progress bar, playlist selector), and manages playback state entirely in the client.
File structure
• Top‐level config:
– vite.config.ts, tsconfig*.json, eslint.config.js, package.json, pnpm-lock.yaml – define build, linting, TS setup and dependencies.
• Public assets:
– index.html (app shell), public/ (static files).
• Source code (src/):
– main.tsx: application entry, mounts React root.
– App.tsx + App.css: top‐level layout.
– assets/: style.css, tracks.json (data source for playlist).
– components/: Player, PlayerControls, PlayerControlButton, PlayerProgressBar, PlaylistSelector – UI building blocks.
– utils/: utility functions (e.g., time formatting, audio helpers).
– types/: TS definitions for Track and Progress.
Key architectural patterns & tech
• Component-based UI (React).
• Unidirectional data flow (state propagated top‐down from App → Player → controls).
• Build & dev server provided by Vite (fast HMR).
• Static JSON as data store (no network calls).
• CSS modularization (component CSS + global CSS).
Main components & their interactions
a. Browser (Client)
– Renders index.html, loads bundled JS/CSS.
b. Vite Dev / Production Server
– Serves static assets & bundles.
c. React App
– App.tsx holds global state (currentTrack, isPlaying, progress).
– Player component orchestrates HTMLMediaElement (Audio).
– Child components (PlayerControls, ProgressBar, PlaylistSelector) receive props/events to modify state.
– utils.ts provides helper functions.
d. Data Source
– tracks.json loaded at startup or via import.
e. Build Pipeline
– vite.config.ts defines asset transforms, TS/JSX compilation.