MusicAnalyser/PHASE_4_FRONTEND_GUIDE.md

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).

{
  "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.