You are an expert AI assistant tasked with creating a Single Page Application (SPA) for a music discovery platform called 'Müzik Keşfi: Algoritma Ötesi' (Music Discovery: Beyond Algorithms). This application aims to address the shortcomings of current AI-driven music recommendation systems, like Spotify's AI DJ, by offering a deeper, more personalized, and nuanced music discovery experience, especially for users with niche tastes (e.g., classical music, jazz, world music). The MVP focuses on a robust user profiling system and an intelligent recommendation engine that combines AI with curated data.
PROJECT OVERVIEW:
- **Purpose:** To provide a superior music discovery experience that goes beyond superficial algorithmic recommendations. It aims to help users find music they'll genuinely love, especially those with less common musical preferences.
- **Problem Solved:** Frustration with generic, repetitive, or inaccurate music recommendations from mainstream platforms. Users with niche tastes often struggle to find relevant content.
- **Value Proposition:** Discover music tailored to your unique taste, explore deeper musical connections, and connect with artists and genres you might have otherwise missed, powered by a smarter, more considerate AI.
TECH STACK:
- **Frontend Framework:** React.js (using functional components and hooks)
- **Styling:** Tailwind CSS for rapid UI development and a consistent design system.
- **State Management:** Zustand for efficient global and local state management. It's lightweight and easy to integrate.
- **Routing:** React Router DOM for navigation within the SPA.
- **API Calls:** Axios for making HTTP requests to a hypothetical backend (for MVP, mock data will be used).
- **Utilities:** Lodash for utility functions, especially for data manipulation.
CORE FEATURES (MVP):
1. **User Profiling & Onboarding:**
* **User Flow:** Upon first visit, users are guided through a brief onboarding process. They select preferred genres (with options for broad and niche categories), artists they like, and perhaps eras or moods. This initial data populates their ZEST profile.
* **Details:** The onboarding should be engaging, not tedious. Use visually appealing selectors for genres/artists. Allow users to skip or refine later.
2. **Intelligent Recommendation Engine:**
* **User Flow:** The main dashboard displays personalized recommendations based on the user's ZEST profile. Recommendations are categorized (e.g., 'New Discoveries for You', 'Similar to Artist X', 'Based on Mood Y'). Users can interact with recommendations: like, dislike, add to playlist, or view more details.
* **Details:** The engine should prioritize diversity and serendipity, not just popularity. It should learn from user feedback (likes/dislikes).
3. **Detailed Music & Artist Pages:**
* **User Flow:** Clicking on a recommended track or artist leads to a dedicated page. This page provides rich information: artist biography, album discography, influences, related artists, genre history, and context for the specific track (e.g., historical significance, instrumentation).
* **Details:** This feature differentiates the app. For niche genres, historical context and curated information are crucial.
4. **Playlist Management:**
* **User Flow:** Users can create, name, edit, and delete their own playlists. They can add songs directly from recommendations or detail pages. Playlists can be marked as public or private.
* **Details:** Simple, intuitive interface for playlist manipulation.
UI/UX DESIGN:
- **Layout:** A clean, modern, and responsive single-page application layout. A persistent sidebar for navigation (Dashboard, My Library, Playlists, Profile) and a main content area. Top bar for search and user settings.
- **Color Palette:** A sophisticated and calming palette. Primary: Dark Navy (#0B1320), Secondary: Deep Teal (#1C2541), Accent: Muted Gold (#B08D57), Text: Off-White (#E0E0E0), Subtle Grays for borders and backgrounds (#3A3A3A, #2C2C2C).
- **Typography:** A combination of a clean sans-serif for UI elements and body text (e.g., Inter or Roboto) and a more classic serif for titles or artist/genre descriptions to evoke a sense of tradition and depth (e.g., Playfair Display or Merriweather).
- **Responsive Design:** Mobile-first approach. Adapts seamlessly to various screen sizes (smartphones, tablets, desktops). Navigation might collapse into a hamburger menu on smaller screens.
- **Key Pages:**
* `/` (Dashboard): Recommendations feed, quick access to recently played.
* `/profile`: User ZEST profile editing, preferences.
* `/artist/:id`: Detailed artist page.
* `/track/:id`: Detailed track page (if needed separately, could be a modal).
* `/playlist/:id`: Playlist view/edit page.
* `/library`: User's saved tracks, liked artists.
COMPONENT BREAKDOWN:
- **`App.js`:** Main application component, sets up routing and global layout.
- **`Layout.js`:** Contains the main structure (Sidebar, TopBar, Content Area).
- **`Sidebar.js`:** Navigation links.
* `Props`: `navItems` (array of objects with label and path).
- **`TopBar.js`:** Search bar, user avatar/menu.
* `Props`: `user` (object).
- **`DashboardPage.js`:** Main landing page after login.
* `Components`: `RecommendationSection.js`, `QuickAccess.js`.
- **`RecommendationSection.js`:** Displays categorized music recommendations.
* `Props`: `recommendations` (array).
* `Components`: `RecommendationCard.js`.
- **`RecommendationCard.js`:** Individual recommendation item (album art, title, artist).
* `Props`: `track` (object), `onLike`, `onAddPlaylist`, `onMoreInfo`.
- **`UserProfilePage.js`:** Displays and allows editing of user ZEST profile.
* `Components`: `ProfileForm.js`, `GenreSelector.js`, `ArtistSelector.js`.
- **`ArtistPage.js`:** Displays detailed information about an artist.
* `Props`: `artistData` (object).
* `Components`: `ArtistBio.js`, `DiscographyList.js`, `RelatedArtists.js`.
- **`PlaylistManager.js`:** Component for creating and managing playlists.
* `Props`: `playlists` (array).
* `Components`: `PlaylistForm.js`, `PlaylistItem.js`.
- **`Zustand Store (store.js)`:** Manages global state (user info, recommendations, playlists).
DATA MODEL:
- **User Object:**
```json
{
"id": "user123",
"name": "Alex",
"email": "alex@example.com",
"profile": {
"preferredGenres": ["Classical Baroque", "Minimalism", "Post-Rock"],
"likedArtists": ["artist456", "artist789"],
"dislikedTracks": ["track001"],
"moods": ["contemplative", "energetic"]
}
}
```
- **Track Object:**
```json
{
"id": "track001",
"title": "Adagio for Strings",
"artistId": "artist001",
"albumId": "album001",
"duration": "0:07:30",
"genre": "Classical Romantic",
"releaseYear": 1905,
"coverArtUrl": "/images/covers/adagio.jpg"
}
```
- **Artist Object:**
```json
{
"id": "artist001",
"name": "Samuel Barber",
"bio": "American composer...",
"genres": ["Classical", "Neoromanticism"],
"influences": ["artist002"],
"relatedArtists": ["artist003", "artist004"],
"albums": ["album001", "album002"]
}
```
- **Playlist Object:**
```json
{
"id": "playlist987",
"name": "Baroque Masterpieces",
"ownerId": "user123",
"trackIds": ["track002", "track005"],
"isPublic": false,
"createdAt": "2023-10-27T10:00:00Z"
}
```
- **State Structure (Zustand):**
```javascript
{
user: null, // User object or null
recommendations: [], // Array of track objects
playlists: [], // Array of playlist objects
currentTrack: null, // Currently playing track
isLoading: false, // Global loading state
error: null // Error message
}
```
ANIMATIONS & INTERACTIONS:
- **Hover Effects:** Subtle background color changes or slight scaling on interactive elements like buttons and recommendation cards.
- **Transitions:** Smooth transitions for page loads and component unmounts using React Transition Group or Framer Motion. Fade-in/out effects for modals and dropdowns.
- **Loading States:** Skeleton loaders or spinners displayed while data is being fetched. Button states should clearly indicate loading (e.g., disabled with a spinner).
- **Micro-interactions:** Visual feedback when liking a track (e.g., heart icon fills), adding to a playlist (e.g., a small confirmation message). Smooth scrolling within content areas.
EDGE CASES:
- **Empty States:** Display informative and visually appealing messages when there are no recommendations, no playlists, or no search results (e.g., "Start by telling us your favorite artists to get recommendations!").
- **Error Handling:** Gracefully handle API errors or network issues. Display user-friendly error messages. Implement retry mechanisms where appropriate.
- **Validation:** Client-side validation for forms (e.g., playlist name cannot be empty). Inform users of validation errors clearly.
- **Accessibility (a11y):** Use semantic HTML elements. Ensure proper ARIA attributes are used. Keyboard navigability for all interactive elements. Sufficient color contrast. Alt text for images.
SAMPLE DATA:
1. **User Profile:**
```json
{
"id": "user456",
"name": "Eleanor",
"profile": {
"preferredGenres": ["Classical Baroque", "Renaissance Polyphony", "Ambient Electronic"],
"likedArtists": ["artist001", "artist111"],
"dislikedTracks": [],
"moods": ["calm", "focused"]
}
}
```
2. **Track Recommendation 1:**
```json
{
"id": "track002",
"title": "Spem in Alium",
"artistId": "artist002",
"albumId": "album003",
"duration": "0:10:45",
"genre": "Renaissance Polyphony",
"releaseYear": 1560,
"coverArtUrl": "/images/covers/spem.jpg"
}
```
3. **Track Recommendation 2:**
```json
{
"id": "track003",
"title": "Telegraph Road",
"artistId": "artist003",
"albumId": "album004",
"duration": "0:14:15",
"genre": "Progressive Rock",
"releaseYear": 1982,
"coverArtUrl": "/images/covers/telegraph.jpg"
}
```
4. **Artist Data (Partial):**
```json
{
"id": "artist001",
"name": "Thomas Tallis",
"bio": "English composer of the English Renaissance...",
"genres": ["Renaissance Polyphony", "English Choral"],
"influences": [],
"relatedArtists": ["artist002", "artist005"],
"albums": ["album003"]
}
```
5. **Artist Data (Partial):**
```json
{
"id": "artist111",
"name": "Brian Eno",
"bio": "English musician, record producer, visual artist... Known for ambient music.",
"genres": ["Ambient", "Electronic", "Art Rock"],
"influences": ["artist112"],
"relatedArtists": ["artist113", "artist114"],
"albums": ["album005", "album006"]
}
```
6. **Playlist Example:**
```json
{
"id": "playlist123",
"name": "Deep Focus Ambient",
"ownerId": "user456",
"trackIds": ["track006", "track007"],
"isPublic": true,
"createdAt": "2023-10-26T15:30:00Z"
}
```
7. **Another Track Recommendation:**
```json
{
"id": "track007",
"title": "Music for Airports 1/1",
"artistId": "artist113",
"albumId": "album007",
"duration": "0:17:05",
"genre": "Ambient",
"releaseYear": 1978,
"coverArtUrl": "/images/covers/eno_airports.jpg"
}
```
8. **Yet Another Track Recommendation (Classical):**
```json
{
"id": "track008",
"title": "Goldberg Variations BWV 988 - Aria",
"artistId": "artist006",
"albumId": "album008",
"duration": "0:03:15",
"genre": "Classical",
"releaseYear": 1741,
"coverArtUrl": "/images/covers/goldberg.jpg"
}
```
9. **Artist for Goldberg Variations:**
```json
{
"id": "artist006",
"name": "Johann Sebastian Bach",
"bio": "German composer of the Baroque period...",
"genres": ["Baroque", "Classical"],
"influences": [],
"relatedArtists": ["artist007", "artist008"],
"albums": ["album008"]
}
```
10. **Genre Data Example:**
```json
{
"name": "Renaissance Polyphony",
"description": "Vocal music characterized by multiple independent melodic lines, popular in the 15th and 16th centuries.",
"keyArtists": ["artist002", "artist009"],
"relatedGenres": ["Late Medieval Music", "Early Baroque"]
}
```
DEPLOYMENT NOTES:
- **Build Command:** `npm run build` or `yarn build`. Ensure the `homepage` property in `package.json` is set correctly if deploying to a subdirectory.
- **Environment Variables:** Use `.env` files for managing environment variables (e.g., `NODE_ENV`, API base URLs if a backend is introduced later). Prefix custom variables with `REACT_APP_`.
- **Performance Optimizations:** Code splitting using React.lazy and Suspense for route-based or component-based lazy loading. Image optimization (using appropriate formats and sizes). Memoization of components and data using `React.memo` and `useMemo`/`useCallback` where necessary.
- **Static Assets:** Place static assets like images and fonts in the `public/` directory or import them directly into components. Ensure proper path resolution.
- **HTTPS:** Always deploy using HTTPS for security.