API Routing & Design

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/v1/api.py
• app/api/v1/init.py
• app/main.py
• app/api/v1/analysis.py
• app/api/v1/song_analysis.py
• app/api/v1/audio_upload.py
• app/api/v1/catalog.py
• CLAUDE.md

Introduction

The MoodTune Backend is built using the FastAPI framework, following a modular and versioned routing architecture. The API is designed to handle music mood analysis, Spotify integration, and audio file processing. It employs a structured pattern where routes are defined in feature-specific modules within app/api/v1/ and aggregated through a central router.

The design emphasizes asynchronous execution for all I/O operations and uses Pydantic models for strict request and response validation. Authentication is handled via Supabase JWT dependencies, ensuring that sensitive analysis history and Spotify operations are protected while allowing guest access for basic audio analysis functions.

Sources: app/main.py:22-31, CLAUDE.md:21-42

Core Application Architecture

The application entry point is app/main.py, which initializes the FastAPI instance and configures essential middleware and integrations.

Initialization & Middleware

The application incorporates Sentry for error tracking and performance monitoring. It also implements Cross-Origin Resource Sharing (CORS) to manage requests from authorized origins defined in the system settings.

The application structure follows a strict hierarchy to ensure maintainability:

• app/main.py: Creates the FastAPI app and mounts global middleware.
• app/api/v1/api.py: Acts as the central hub, aggregating all feature-specific routers.
• app/api/v1/: Contains individual route modules (e.g., analysis.py, song_analysis.py).

Sources: app/main.py:10-44, CLAUDE.md:21-30

API Routing Structure

The project uses a tiered routing system. The api_router in app/api/v1/api.py includes routers from various modules, which are then included in the main application with a /api/v1 prefix.

Key API Modules

Module	Purpose	Authentication
analysis.py	Playlist-level mood analysis and history	Required (get_current_user)
song_analysis.py	Individual song analysis via upload or Spotify ID	Required (get_current_user)
audio_upload.py	Guest audio file analysis	Optional/Guest
catalog.py	Analysis of tracks from external catalog streams	Optional (optional_get_current_user)

Sources: app/api/v1/api.py, app/api/v1/analysis.py:27, app/api/v1/audio_upload.py:12, app/api/v1/catalog.py:20

Routing Implementation Pattern

New endpoints follow a standardized implementation sequence:

1. Define Pydantic models in app/schemas/.
2. Implement business logic in app/services/.
3. Create the route in app/api/v1/.
4. Register the router in app/api/v1/api.py.

Sources: CLAUDE.md:32-38

Analysis Endpoints & Data Flow

The API supports three primary analysis flows: Spotify Playlist Analysis, Individual Song Analysis, and Raw Audio Upload Analysis.

Playlist Analysis Flow

This flow involves fetching metadata and audio features from the Spotify API, processing them through an analysis service, and persisting results to Supabase.

Audio Upload and Catalog Analysis

For raw audio files, the API utilizes a local audio_analysis_service powered by librosa.

• Direct Upload: Users post a multipart/form-data file to /api/v1/audio-upload/analyze. The system validates the file format and size before processing.
• Catalog Analysis: The system downloads audio from a URL (e.g., Jamendo) server-side and applies the same librosa-based pipeline.

Sources: app/api/v1/audio_upload.py:12-68, app/api/v1/catalog.py:20-80

Request Validation and Response Design

The API design relies heavily on Pydantic models (Schemas) to ensure data integrity.

Common Parameters and Constraints

The API enforces several constraints via FastAPI.Query and settings:

• Pagination: Most history endpoints use limit (default 50, max 100) and offset parameters.
• Track Limits: Playlist analysis requires a minimum of 5 tracks and defaults to a maximum of 50 for performance.
• File Size: Uploads are restricted by settings.MAX_UPLOAD_SIZE_MB (verified in audio_upload.py and catalog.py).
• Audio Formats: Only formats listed in settings.ALLOWED_AUDIO_FORMATS are accepted.

Sources: app/api/v1/analysis.py:12-16, app/api/v1/song_analysis.py:121-131, app/api/v1/audio_upload.py:30-42

Error Handling

The API uses fastapi.HTTPException to return standardized error responses. Common status codes include:

• 400 Bad Request: Missing files or insufficient tracks.
• 401 Unauthorized: Invalid or missing Supabase JWT.
• 413 Request Entity Too Large: File exceeds size limits.
• 502 Bad Gateway: External API (Spotify/Jamendo) communication failure.

Sources: app/api/v1/analysis.py:86-98, app/api/v1/song_analysis.py:120-135, CLAUDE.md:46-50

Conclusion

The API routing and design of MoodTune Backend facilitate a clean separation between entry points, business logic, and data validation. By utilizing FastAPI's router system and asynchronous patterns, the architecture supports both high-level Spotify integrations and resource-intensive audio processing. The centralized aggregation of routes in app/api/v1/api.py provides a scalable foundation for adding new music analysis features.