Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The MoodTune Backend is a FastAPI-powered service designed to perform audio mood analysis using the librosa library. It integrates with Spotify for playlist data and utilizes Supabase (PostgreSQL) for data persistence. The system architecture supports both automated analysis of Spotify tracks and manual analysis of uploaded audio files.
Sources: CLAUDE.md:7-10, README.md:1-5
Development Environment Setup
To begin development, you must configure the Python environment and local environment variables. The project utilizes a venv for dependency management and requires several external service keys for full functionality.
Prerequisites and Installation
- Python Environment: Create and activate a virtual environment.
- Dependency Installation: Install required packages via
requirements.txt. - Local Server: Run the application using
uvicorn.
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
Sources: README.md:20-25, CLAUDE.md:14-23
Environment Configuration
A .env file must be created at the root, based on env.sample. The following table summarizes the required configuration keys:
| Category | Variable | Description |
|---|---|---|
| Supabase | SUPABASE_URL, SUPABASE_KEY | Connection details for the Postgres database. |
| Spotify | SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET | Credentials for the Spotify Web API. |
| Auth | SECRET_KEY, ALGORITHM | Security settings for JWT handling. |
| Storage | TEMP_AUDIO_DIR | Directory for temporary audio processing. |
Sources: README.md:7-13, TEST_PLAN.md:14-22, app/services/audio_analysis_service.py:270-275
System Architecture
The backend follows a modular structure where API routers handle HTTP logic, schemas define data shapes, and services contain the core business and signal processing logic.
Directory Structure
app/
├── api/v1/ # API endpoints (song_analysis, catalog, spotify)
├── core/ # Configuration and client initializers
├── schemas/ # Pydantic request/response models
├── services/ # Librosa analysis and Spotify API logic
└── models/ # Database interaction helpers
Sources: CLAUDE.md:25-38
Core Service Flow
The AudioAnalysisService is the central component for processing audio data. It handles the conversion of raw audio into mood features.
This diagram illustrates the high-level request lifecycle for an audio analysis task.
Sources: app/services/audio_analysis_service.py:46-100, app/api/v1/song_analysis.py:165-200, CLAUDE.md:40-48
Database Initialization
MoodTune uses Supabase for storage. Before running the application, ensure the database schema is initialized. The project includes SQL files to create the necessary tables and Row Level Security (RLS) policies.
Core Tables
song_analyses: Stores results of individual track analyses, including JSONB blobs for mood features.playlist_analyses: Stores aggregated mood data for entire Spotify playlists.spotify_connections: Manages OAuth tokens for users.
Sources: db/song_analyses.sql:1-8, db/playlist_analyses.sql:1-8, TEST_PLAN.md:24-27
Row Level Security (RLS)
The database enforces isolation between users. Each table has policies ensuring users can only interact with their own data.
CREATE POLICY "Users can view own song analyses"
ON song_analyses FOR SELECT
USING (auth.uid() = user_id);
Sources: db/song_analyses.sql:13-26
Deployment
The project is configured for deployment on Railway. The railway.toml file defines the build and start commands used by the Railway platform.
| Command Type | Configuration |
|---|---|
| Root | moodtune-backend |
| Build | pip install -r requirements.txt |
| Start | uvicorn app.main:app --host 0.0.0.0 --port $PORT |
| Health Check | /health |
Sources: railway.toml:1-5, README.md:15-18
Verification and Testing
To verify the installation, the project provides a shell script (test_api.sh) and a comprehensive test plan.
Basic Health Check
You can verify the server is running by hitting the health endpoint:
curl -s "http://localhost:8000/health" | jq '.'
Sources: test_api.sh:76-78
Running Automated Tests
The project uses pytest for backend verification.
# Run all tests
pytest tests/ -v
# Run specific analysis tests
pytest tests/test_analysis.py -v
Sources: CLAUDE.md:18-23
This "Getting Started" guide provides the essential foundation for setting up the MoodTune Backend, from local environment configuration to deployment. By following these steps, developers can ensure a consistent and functional development environment.