Statify 🎵

Spotify statistics, no bs

A modern web application that connects to your Spotify account and displays comprehensive listening statistics and insights.

Features

• 🔐 Secure Spotify OAuth authentication
• 📊 Top tracks and artists analysis
• 🎨 Genre distribution insights
• 📈 Listening habits over time
• 🎵 Recently played tracks
• 📱 Responsive design for all devices

Tech Stack

Backend

• FastAPI - Modern Python web framework
• Python 3.9+ - Core backend language
• Spotify Web API - Music data source
• Pydantic - Data validation and serialization

Frontend

• React 18 - UI framework
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first styling
• React Router - Client-side routing
• Chart.js - Data visualization

Quick Start

Prerequisites

• Python 3.9+
• Node.js 16+
• Spotify Developer Account

1. Clone the repository

git clone https://github.com/fromagge/statify.git
cd statify

2. Set up Spotify App

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Add redirect URI: http://localhost:8000/auth/callback
4. Note your Client ID and Client Secret

3. Backend Setup

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Copy environment template and fill in your Spotify credentials
cp .env.example .env
# Edit .env with your Spotify Client ID and Secret

# Run the backend
uvicorn main:app --reload --port 8000

4. Frontend Setup

cd frontend
npm install
npm start

The app will be available at:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs

Development

Using Docker (Recommended)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Project Structure

statify/
├── backend/                 # FastAPI backend
│   ├── main.py             # Application entry point
│   ├── auth.py             # Spotify OAuth handling
│   ├── spotify_service.py  # Spotify API integration
│   ├── models.py           # Data models
│   └── routes/             # API endpoints
├── frontend/               # React frontend
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── contexts/       # React contexts
│   │   └── services/       # API clients
│   └── public/
├── docs/                   # Documentation
└── scripts/               # Development scripts

API Endpoints

Authentication

• GET /auth/login - Initiate Spotify OAuth
• GET /auth/callback - Handle OAuth callback
• POST /auth/refresh - Refresh access token

User Data

• GET /user/profile - Get user profile
• GET /user/top-tracks - Get top tracks
• GET /user/top-artists - Get top artists
• GET /user/recently-played - Get recently played tracks

Statistics

• GET /stats/overview - Get overview statistics
• GET /stats/genres - Get genre distribution
• GET /stats/listening-habits - Get listening patterns

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Spotify Web API for providing music data
• FastAPI for the excellent Python framework
• React for the powerful UI library