mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
f4432154b6
- Refactor Database: Add `Artist` model, M2M relationship, and `AnalysisSnapshot` model. - Backend Services: Implement `StatsService` for computable metrics and `NarrativeService` for Gemini LLM integration. - Fix Ingestion: Correctly handle multiple artists per track and backfill existing data. - Testing: Add unit tests for statistics logic and live verification scripts. - Documentation: Add `PHASE_4_FRONTEND_GUIDE.md`.
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# Phase 4 Frontend Implementation Guide
|
|
|
|
This guide details how to consume the data generated by the Phase 3 Backend (Analysis & LLM Engine) and how to display it in the frontend.
|
|
|
|
## 1. Data Source
|
|
|
|
The backend now produces **Analysis Snapshots**. You should create an API endpoint (e.g., `GET /api/analysis/latest`) that returns the most recent snapshot.
|
|
|
|
### JSON Payload Structure
|
|
|
|
The response object contains two main keys: `metrics_payload` (calculated numbers) and `narrative_report` (LLM text).
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"date": "2024-12-25T12:00:00Z",
|
|
"period_label": "last_30_days",
|
|
"metrics_payload": {
|
|
"volume": { ... },
|
|
"time_habits": { ... },
|
|
"sessions": { ... },
|
|
"vibe": { ... },
|
|
"era": { ... },
|
|
"skips": { ... }
|
|
},
|
|
"narrative_report": {
|
|
"vibe_check": "...",
|
|
"patterns": ["..."],
|
|
"persona": "...",
|
|
"roast": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. UI Components & Display Strategy
|
|
|
|
### A. Hero Section ("The Vibe Check")
|
|
**Data Source:** `narrative_report`
|
|
- **Headline:** Display `narrative_report.persona` as a large badge/title (e.g., "The Focused Fanatic").
|
|
- **Narrative:** Display `narrative_report.vibe_check` as the main text.
|
|
- **Roast:** Add a small, dismissible "Roast Me" alert box containing `narrative_report.roast`.
|
|
|
|
### B. "The Vibe" Radar Chart
|
|
**Data Source:** `metrics_payload.vibe`
|
|
- Use a **Radar Chart** (Spider Chart) with the following axes (0.0 - 1.0):
|
|
- Energy (`avg_energy`)
|
|
- Valence (`avg_valence`)
|
|
- Danceability (`avg_danceability`)
|
|
- Acousticness (`avg_acousticness`)
|
|
- Instrumentalness (`avg_instrumentalness`)
|
|
- **Tooltip:** Show the exact value.
|
|
|
|
### C. Listening Habits (Time & Sessions)
|
|
**Data Source:** `metrics_payload.time_habits` & `metrics_payload.sessions`
|
|
- **Hourly Heatmap:** Use a bar chart for `metrics_payload.time_habits.hourly_distribution` (0-23 hours). Highlight the `peak_hour`.
|
|
- **Session Stats:** Display "Average Session" stats:
|
|
- `sessions.avg_minutes` (mins)
|
|
- `sessions.avg_tracks` (tracks)
|
|
- `sessions.count` (total sessions)
|
|
|
|
### D. Top Favorites
|
|
**Data Source:** `metrics_payload.volume`
|
|
- **Lists:** Display Top 5 Tracks, Artists, and Genres.
|
|
- **Images:** You will need to fetch Artist/Track images from Spotify API using the IDs provided in the lists (the current snapshot only stores names/counts for simplicity, but the IDs are available in the backend if you expand the serializer). *Note: Phase 3 backend currently returns names. For Phase 4, ensure the API endpoint enriches these with Spotify Image URLs.*
|
|
|
|
### E. Era Analysis
|
|
**Data Source:** `metrics_payload.era`
|
|
- **Musical Age:** Display `musical_age` (e.g., "1998") prominently.
|
|
- **Distribution:** Pie chart for `decade_distribution`.
|
|
|
|
### F. Attention Span (Skips)
|
|
**Data Source:** `metrics_payload.skips`
|
|
- **Metric:** Display "Skip Rate" (`skip_rate`) as a percentage.
|
|
- **Insight:** "You skipped X tracks this month."
|
|
|
|
---
|
|
|
|
## 3. Integration Tips
|
|
|
|
- **Caching:** The backend stores snapshots. You do NOT need to trigger a calculation on page load. Just fetch the latest snapshot.
|
|
- **Theme:** The app uses Ant Design Dark Mode. Stick to Spotify colors (Black/Green/White) but add accent colors based on the "Vibe" (e.g., High Energy = Red/Orange, Low Energy = Blue/Purple).
|
|
- **Expansion:** Future snapshots allow for "Trend" views. You can graph `metrics_payload.volume.total_plays` over the last 6 snapshots to show activity trends.
|