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