Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune is a FastAPI-based Python backend designed to provide automated mood analysis for music. The system utilizes librosa for direct audio signal processing and integrates with the Spotify API to analyze existing playlists and tracks. It follows an asynchronous architecture, leveraging Pydantic for data validation and Supabase for persistent storage.
The backend is structured into distinct layers: API routers for request handling, services for business and signal processing logic, and a data layer utilizing the Supabase Python client for PostgreSQL interactions.
Sources: CLAUDE.md:1-15, app/services/audio_analysis_service.py:12-25
System Component Hierarchy
The project follows a modular structure where concerns are separated into core configuration, API endpoints, data schemas, and specialized services.
| Component | Responsibility |
|---|---|
| API Layer | Handles HTTP requests, authentication, and endpoint routing. |
| Service Layer | Contains business logic, Spotify API integration, and audio analysis signal processing. |
| Core Layer | Manages environment configurations, security settings, and global constants. |
| Data Layer | Defines Pydantic schemas and handles Supabase database operations. |
Sources: CLAUDE.md:21-35, app/core/config.py:31-70
Logic Flow for Audio Analysis
The following diagram illustrates the high-level request flow when a user uploads a file or initiates a catalog analysis.
The system writes incoming audio to a temporary directory before processing to ensure librosa can access the file stream.
Sources: app/services/audio_analysis_service.py:37-55, app/api/v1/audio_upload.py:46-60
Audio Processing & Mood Classification
The core value of the architecture lies in its ability to translate raw audio signals into human-readable mood categories. This is achieved through two primary modules: AudioAnalysisService (for raw audio) and analysis_service (for Spotify metadata).
Direct Audio Analysis (Librosa)
For uploaded files, the system extracts features including tempo (BPM), RMS energy, spectral centroid (brightness), and chroma.
- Tempo & Energy: Used to estimate "Danceability".
- Brightness & Tempo: Used to estimate "Valence" (happiness).
- Harmonic/Percussive Separation: Used to determine texture labels (Smooth, Textured, Rough).
Sources: app/services/audio_analysis_service.py:80-115, app/services/audio_analysis_service.py:165-185
Metadata-Based Analysis (Spotify)
When analyzing Spotify playlists, the system uses pre-calculated audio features provided by the Spotify API, applying threshold-based logic to categorize the mood.
Data Persistence & Security
The system uses Supabase as its primary database. It relies on Row Level Security (RLS) to ensure that users can only access their own analysis history.
Database Schema: Song Analyses
The song_analyses table stores the results of individual track evaluations.
Sources: db/song_analyses.sql:1-9
Authentication Pattern
The backend uses a dependency injection pattern for security. Routes requiring authentication utilize Depends(get_current_user), which validates the Supabase JWT.
Sources: CLAUDE.md:46-52, app/api/v1/song_analysis.py:48-52
Infrastructure Configuration
The application is configured to run on Railway and supports multiple environments (development, staging, production).
| Setting | Default/Requirement | Description |
|---|---|---|
MAX_UPLOAD_SIZE_MB | 15 MB | Maximum size for uploaded audio files. |
ALLOWED_AUDIO_FORMATS | mp3, m4a, flac, wav, ogg | Supported extensions for analysis. |
TEMP_AUDIO_DIR | /tmp/moodtune-audio | Storage for librosa processing. |
BACKEND_CORS_ORIGINS | Env-dependent | Allowed frontend origins. |
Sources: app/core/config.py:72-85, railway.toml:1-5
Summary of Analysis Operations
The system provides a comprehensive workflow from raw signal to persistent data. By separating direct audio processing (via Librosa) from metadata analysis (via Spotify), the architecture supports both user-uploaded content and existing streaming libraries. Security is managed through centralized dependencies, and scalability is addressed through the use of asynchronous I/O and cloud-native storage.
Sources: CLAUDE.md:37-44, app/api/v1/song_analysis.py:155-180