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