Cycle Planner

A web application for cycle instructors to create AI-powered lesson plans with Spotify music integration.

Features

• AI-generated lesson plans using Claude
• Spotify integration for music playback
• Customizable workout segments with tempo-matched songs
• Supabase authentication and database storage

Requirements

• Python 3.11+
• A Supabase project
• Spotify Developer account
• Anthropic API key

Installation

1. Clone the repository:

   git clone <repository-url>
   cd cycle-planner

2. Create and activate a virtual environment:

   python -m venv .venv
   
   # Windows
   .venv\Scripts\activate
   
   # macOS/Linux
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Copy the example environment file:

   cp .env.example .env

5. Configure environment variables (see below)

6. Run database migrations:

   alembic upgrade head

Environment Variables

Create a .env file with the following variables:

Claude API

• ANTHROPIC_API_KEY - Your Anthropic API key from https://console.anthropic.com/

Supabase

• SUPABASE_URL - Your Supabase project URL (found in Settings > API)
• SUPABASE_KEY - Your Supabase anon/public key
• SUPABASE_SERVICE_KEY - Your Supabase service role key
• DATABASE_URL - PostgreSQL connection string (found in Settings > Database > Connection string > URI)

App

• APP_ENV - Environment mode (development or production)
• APP_SECRET_KEY - Secret key for session management (use a random string)
• CORS_ORIGINS - Comma-separated list of allowed origins (e.g., http://localhost:8000,https://yourdomain.com)

Spotify

Get these from https://developer.spotify.com/dashboard:

• SPOTIFY_CLIENT_ID - Your Spotify app client ID
• SPOTIFY_CLIENT_SECRET - Your Spotify app client secret
• SPOTIFY_REDIRECT_URI - OAuth callback URL (e.g., http://localhost:8000/api/spotify/callback)

GetSongBPM (Optional)

• GETSONGBPM_API_KEY - API key from https://getsongbpm.com/api (used as fallback for tempo data)

Running the Application

Start the development server:

uvicorn main:app --reload

The application will be available at http://localhost:8000

Spotify Setup

1. Create an app at https://developer.spotify.com/dashboard
2. Add your redirect URI to the app settings (e.g., http://localhost:8000/api/spotify/callback)
3. Copy the Client ID and Client Secret to your .env file

Supabase Setup

1. Create a new project at https://supabase.com
2. Copy the project URL, anon key, and service role key to your .env file
3. Get the database connection string from Settings > Database > Connection string > URI
4. Run migrations with alembic upgrade head to create the required tables

Authentication Configuration

In your Supabase dashboard, configure the following:

URL Configuration (Authentication → URL Configuration):

• Site URL: https://yourdomain.com
• Redirect URLs: Add https://yourdomain.com/**

Password Reset (Authentication → Email Templates → Reset Password):

• Update the action button URL to: {{ .SiteURL }}/reset-password

Custom SMTP (Optional - Authentication → SMTP Settings):

• Enable custom SMTP to send emails from your own domain instead of Supabase's default address

GetSongBPM Setup (Optional)

GetSongBPM is used as a fallback when Spotify audio features are unavailable.

1. Create an account at https://getsongbpm.com/api
2. Set your Backlink URL to: https://yourdomain.com
3. Copy the API key to your .env file

Redirect URLs Reference

When deploying to production, configure these URLs in each service:

Service	URL Type	Development	Production
Spotify	Redirect URI	http://localhost:8000/api/spotify/callback	https://yourdomain.com/api/spotify/callback
Supabase	Site URL	http://localhost:8000	https://yourdomain.com
Supabase	Redirect URLs	http://localhost:8000/**	https://yourdomain.com/**
GetSongBPM	Backlink URL	http://localhost:8000	https://yourdomain.com