music-and-you

Music and You - Frontend

A modern React/Next.js frontend for the Music and You personality prediction application.

🚀 Features

Core Functionality

User Experience

Developer Experience

📁 Project Structure

frontend/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── layout.tsx         # Root layout with providers
│   │   ├── page.tsx           # Homepage with hero and features
│   │   ├── providers.tsx      # React Query and toast providers
│   │   └── globals.css        # Global styles and Tailwind
│   ├── components/            # Reusable UI components
│   │   ├── ui/               # Base UI components (Button, Card, etc.)
│   │   ├── charts/           # Data visualization components
│   │   ├── forms/            # Form components and validation
│   │   └── layout/           # Layout components (Header, Footer, etc.)
│   ├── lib/                  # Utility libraries
│   │   ├── api.ts            # API client with auth and error handling
│   │   └── utils.ts          # Utility functions and helpers
│   ├── stores/               # Zustand state management
│   │   └── index.ts          # Auth, analysis, and personality stores
│   ├── types/                # TypeScript type definitions
│   │   └── index.ts          # Comprehensive type system
│   └── hooks/                # Custom React hooks
├── public/                   # Static assets
├── package.json             # Dependencies and scripts
├── tailwind.config.js       # Tailwind CSS configuration
├── tsconfig.json           # TypeScript configuration
└── next.config.js          # Next.js configuration

🛠 Installation & Setup

Prerequisites

Quick Start

  1. Navigate to frontend directory: 
    cd frontend
  2. Install dependencies: 
    npm install
# or
yarn install
  3. Set up environment variables: 
    cp .env.example .env.local

    Configure the following variables:

    NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_NAME="Music and You"
  4. Start development server: 
    npm run dev
# or
yarn dev
  5. Open in browser: Visit http://localhost:3000

🔧 Development Commands

# Development
npm run dev              # Start development server
npm run build           # Build for production
npm run start           # Start production server

# Code Quality
npm run lint            # Run ESLint
npm run type-check      # Run TypeScript compiler

# Testing
npm run test            # Run Jest tests
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Generate coverage report

# Storybook
npm run storybook       # Start Storybook server
npm run build-storybook # Build Storybook

🎨 Component Library

Base Components

Specialized Components

Layout Components

📊 State Management

Auth Store (useAuthStore)

{
  isAuthenticated: boolean;
  user: User | null;
  accessToken: string | null;
  platforms: { spotify: boolean; lastfm: boolean; youtube_music: boolean };
  loginWithSpotify: () => Promise<void>;
  logout: () => Promise<void>;
}

Analysis Store (useAnalysisStore)

{
  currentAnalysis: MusicAnalysis | null;
  loading: LoadingState;
  startAnalysis: (timeRange?: string) => Promise<void>;
  getLatestAnalysis: () => Promise<void>;
}

Personality Store (usePersonalityStore)

{
  currentPrediction: PersonalityPrediction | null;
  submitQuestionnaire: (data: QuestionnaireData) => Promise<void>;
  getPrediction: (id?: string) => Promise<void>;
}

🎯 Key Features Implementation

Authentication Flow

  1. User clicks “Connect with Spotify”
  2. Redirect to Spotify OAuth2 authorization
  3. Handle callback with authorization code
  4. Exchange code for access/refresh tokens
  5. Store tokens securely and update auth state

Music Analysis Pipeline

  1. Fetch user’s listening history from connected platforms
  2. Extract acoustic features using Spotify’s Audio Features API
  3. Calculate behavioral metrics (diversity, exploration, etc.)
  4. Analyze temporal patterns and session characteristics
  5. Display comprehensive analysis with visualizations

Personality Prediction Workflow

  1. Present TIPI (Ten Item Personality Inventory) questionnaire
  2. Combine questionnaire responses with music features
  3. Generate Big Five personality predictions using ML models
  4. Visualize results with confidence intervals and explanations
  5. Provide actionable insights and comparisons

🔒 Security & Privacy

Data Protection

📱 Responsive Design

Breakpoints

Mobile-First Features

🎨 Design System

Color Palette

Typography

Spacing & Layout

🧪 Testing Strategy

Unit Tests

Integration Tests

🚀 Deployment

Production Build

npm run build
npm run start

Environment Configuration

# Production
NEXT_PUBLIC_API_URL=https://api.musicandyou.com
NEXT_PUBLIC_APP_NAME="Music and You"
NODE_ENV=production

Performance Optimization

📖 Usage Examples

Basic Authentication

import { useAuthStore } from '@/stores';

function LoginButton() {
  const { loginWithSpotify, loading } = useAuthStore();
  
  return (
    <Button
      onClick={loginWithSpotify}
      loading={loading.isLoading}
      variant="spotify"
    >
      Connect with Spotify
    </Button>
  );
}

Music Analysis

import { useAnalysisStore } from '@/stores';

function AnalysisButton() {
  const { startAnalysis, loading } = useAnalysisStore();
  
  return (
    <Button
      onClick={() => startAnalysis('medium_term')}
      loading={loading.isLoading}
    >
      Analyze My Music
    </Button>
  );
}

Personality Prediction

import { usePersonalityStore } from '@/stores';

function PersonalityResults() {
  const { currentPrediction } = usePersonalityStore();
  
  if (!currentPrediction) return <div>No prediction available</div>;
  
  return (
    <PersonalityChart
      scores={currentPrediction.scores}
      confidence={currentPrediction.overall_confidence}
    />
  );
}

🤝 Contributing

Development Workflow

  1. Fork the repository
  2. Create a feature branch
  3. Make changes with tests
  4. Run linting and type checking
  5. Submit a pull request

Code Style

Built with ❤️ for the Music and You project

This site is open source. Improve this page.