# FRONTEND COMPONENTS KNOWLEDGE BASE

**Directory:** `frontend/src/components`

## OVERVIEW

This directory contains the primary UI components for the MusicAnalyser dashboard. The architecture follows a **Presentational & Container pattern**, where `Dashboard.jsx` acts as the main container orchestrating data fetching and state, while sub-components handle specific visualizations and data displays.

The UI is built with **React (Vite)**, utilizing **Tailwind CSS** for custom layouts/styling and **Ant Design** for basic UI primitives. Data visualization is powered by **Recharts** and custom SVG/Tailwind grid implementations.

## WHERE TO LOOK

| Component | Role | Complexity |
|-----------|------|------------|
| `Dashboard.jsx` | Main entry point. Handles API interaction (`/api/snapshots`), data caching (`localStorage`), and layout. | High |
| `VibeRadar.jsx` | Uses `Recharts` RadarChart to visualize "Sonic DNA" (acousticness, energy, valence, etc.). | High |
| `HeatMap.jsx` | Custom grid implementation for "Chronobiology" (listening density across days/time blocks). | Medium |
| `StatsGrid.jsx` | Renders high-level metrics (Minutes Listened, "Obsession" Track, Hipster Score) in a responsive grid. | Medium |
| `ListeningLog.jsx` | Displays a detailed list of recently played tracks. | Low |
| `NarrativeSection.jsx` | Renders AI-generated narratives, "vibe checks", and "roasts". | Low |
| `TopRotation.jsx` | Displays top artists and tracks with counts and popularity bars. | Medium |

## CONVENTIONS

- **Styling**: Leverages Tailwind utility classes.
    - **Key Colors**: `primary` (#256af4), `card-dark` (#1e293b), `card-darker` (#0f172a).
    - **Glassmorphism**: Use `glass-panel` for semi-transparent headers and panels.
- **Icons**: Standardized on **Google Material Symbols** (`material-symbols-outlined`).
- **Data Flow**: Unidirectional. `Dashboard.jsx` fetches data and passes specific slices down to sub-components via props.
- **Caching**: API responses are cached in `localStorage` with a date-based key (`sonicstats_v2_YYYY-MM-DD`) to minimize redundant requests.
- **Visualizations**: 
    - Use `Recharts` for standard charts (Radar, Line).
    - Use Tailwind grid and relative/absolute positioning for custom visualizations (HeatMap, Mood Clusters).
- **Responsiveness**: Use responsive grid prefixes (`grid-cols-1 md:grid-cols-2 lg:grid-cols-4`) to ensure dashboard works across devices.
