mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
887e78bf47
Major changes: - Add skip tracking: poll currently-playing every 15s, detect skips (<30s listened) - Add listening-log and sessions API endpoints - Fix ReccoBeats client to extract spotify_id from href response - Compress heatmap from 24 hours to 6 x 4-hour blocks - Add OpenAI support in narrative service (use max_completion_tokens for new models) - Add ListeningLog component with timeline and list views - Update all frontend components to use real data (album art, play counts) - Add docker-compose external network (dockernet) support - Add comprehensive documentation (API, DATA_MODEL, ARCHITECTURE, FRONTEND) - Add unit tests for ingest and API endpoints
62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# Frontend Documentation
|
|
|
|
The frontend is a React application built with Vite and Tailwind CSS. It uses Ant Design for some UI components and Recharts for data visualization.
|
|
|
|
## Main Components
|
|
|
|
### `Dashboard.jsx`
|
|
The primary layout component that manages data fetching and state.
|
|
- **Features**:
|
|
- Handles API calls to `/snapshots` and `/trigger-analysis`.
|
|
- Implements local storage caching to reduce API load.
|
|
- Displays a global loading state during analysis.
|
|
- Contains the main header with a refresh trigger.
|
|
|
|
### `NarrativeSection.jsx`
|
|
Displays the AI-generated qualitative analysis.
|
|
- **Props**:
|
|
- `narrative`: Object containing `persona`, `vibe_check_short`, and `roast`.
|
|
- `vibe`: Object containing audio features used to generate dynamic tags.
|
|
- **Purpose**: Gives the user a "identity" based on their music taste (e.g., "THE MELANCHOLIC ARCHITECT").
|
|
|
|
### `StatsGrid.jsx`
|
|
A grid of high-level metric cards.
|
|
- **Props**:
|
|
- `metrics`: The `metrics_payload` from a snapshot.
|
|
- **Displays**:
|
|
- **Minutes Listened**: Total listening time converted to days.
|
|
- **Obsession**: The #1 most played track with album art background.
|
|
- **Unique Artists**: Count of different artists encountered.
|
|
- **Hipster Score**: A percentage indicating how obscure the user's taste is.
|
|
|
|
### `VibeRadar.jsx`
|
|
Visualizes the "Sonic DNA" of the user.
|
|
- **Props**:
|
|
- `vibe`: Audio feature averages (acousticness, danceability, energy, etc.).
|
|
- **Visuals**:
|
|
- **Radar Chart**: Shows the balance of audio features.
|
|
- **Mood Clusters**: Floating bubbles representing "Party", "Focus", and "Chill" percentages.
|
|
- **Whiplash Meter**: Shows volatility in tempo, energy, and valence between consecutive tracks.
|
|
|
|
### `TopRotation.jsx`
|
|
A horizontal scrolling list of the most played tracks.
|
|
- **Props**:
|
|
- `volume`: Object containing `top_tracks` array.
|
|
- **Purpose**: Quick view of recent favorites.
|
|
|
|
### `HeatMap.jsx`
|
|
Visualizes when the user listens to music.
|
|
- **Props**:
|
|
- `timeHabits`: Compressed heatmap data (7x6 grid for days/time blocks).
|
|
- `sessions`: List of recent listening sessions.
|
|
- **Visuals**:
|
|
- **Grid**: Days of the week vs. Time blocks (12am, 4am, etc.).
|
|
- **Session Timeline**: Vertical list of recent listening bouts with session type (Marathon vs. Micro).
|
|
|
|
### `ListeningLog.jsx`
|
|
A detailed view of individual plays.
|
|
- **Features**:
|
|
- **Timeline View**: Visualizes listening sessions across the day for the last 7 days.
|
|
- **List View**: A table of individual plays with skip status detection.
|
|
- **Timeframe Filter**: Toggle between 24h, 7d, 14d, and 30d views.
|