Analysis History Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Analysis History Tracking is a core module within the MoodTune backend responsible for persisting and retrieving the results of both playlist-level and individual song-level mood analyses. It serves as a durable record of a user's interactions with the analysis engine, allowing them to revisit past results without re-processing audio data or re-querying external APIs like Spotify.
The system is bifurcated into two primary tracking domains: Playlist Analysis, which aggregates Spotify audio features to classify the mood of entire collections, and Song Analysis, which tracks detailed mood metrics derived from direct audio processing (librosa) or Spotify metadata. All historical data is stored in Supabase (PostgreSQL) with Row Level Security (RLS) ensuring that users can only access their own analysis records.
Data Architecture and Persistence
The persistence layer uses two distinct SQL tables to store historical data. Both tables leverage JSONB to store complex mood result objects, providing flexibility for evolving analysis schemas while maintaining relational links to the Supabase auth.users table.
Database Schema
The following ER diagram illustrates the relationship between users and their analysis history:
The database structure enforces user isolation through foreign key references and descending timestamp indexing for efficient history retrieval.
Sources: db/playlist_analyses.sql:1-12, db/song_analyses.sql:1-12
Data Models
The system uses Pydantic models to ensure type safety when fetching history from the database and returning it via the API.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the analysis record |
user_id | UUID | Owner of the analysis |
playlist_id / track_id | String | External ID (e.g., Spotify ID) |
mood_results | JSONB / Object | Detailed metrics (Valence, Energy, Mood Category) |
created_at | DateTime | Timestamp of the analysis |
Sources: app/schemas/analysis.py:65-71, app/schemas/song_analysis.py:53-61
Analysis Retrieval Logic
History is retrieved through dedicated CRUD (Create, Read, Update, Delete) modules that interface with the Supabase client. These functions use asynchronous executors to handle I/O-bound database operations without blocking the FastAPI event loop.
Retrieval Process Flow
The retrieval flow ensures that the most recent analyses are returned first using pagination.
Sources: app/crud/analysis.py:44-59, app/crud/song_analysis.py:42-57
Key Retrieval Functions
get_user_analyses(user_id, limit, offset): Fetches a paginated list of playlist analyses for a specific user. Sources: app/crud/analysis.py:44-59get_user_song_analyses(user_id, limit, offset): Fetches a paginated list of individual song analyses. Sources: app/crud/song_analysis.py:42-57get_playlist_analysis(analysis_id): Retrieves a single, detailed playlist analysis record by its unique UUID. Sources: app/crud/analysis.py:28-42
API Implementation
The history tracking is exposed through two primary API routers: /api/v1/analysis for playlists and /api/v1/song for individual tracks.
Endpoint Summary
| Endpoint | Method | Purpose |
|---|---|---|
/analysis/history | GET | List user's playlist analysis history |
/analysis/{analysis_id} | GET | Retrieve specific playlist analysis details |
/song/history | GET | List user's individual song analysis history |
Sources: app/api/v1/analysis.py:129-144, app/api/v1/song_analysis.py:42-65
Security and Ownership Verification
For specific record retrieval, the system performs a strict ownership check. Even if a valid UUID is provided, the backend compares the user_id stored in the database record against the user_id extracted from the current user's JWT.
# Example of ownership verification in analysis.py
analysis = await crud_analysis.get_playlist_analysis(analysis_id)
if not analysis:
raise HTTPException(status_code=404, detail="Analysis not found")
analysis_user_id = analysis.get("user_id")
if str(analysis_user_id) != str(user_id):
raise HTTPException(status_code=403, detail="Not authorized")
Sources: app/api/v1/analysis.py:158-168
Integration with Analysis Services
The history tracking module is the final step in the analysis pipeline. Once the analysis_service (for Spotify features) or audio_analysis_service (for raw audio) completes its computation, the results are immediately passed to the CRUD layer for persistence.
Analysis Pipeline Sequence
This sequence ensures that every successful analysis is recorded in the user's history before the response is sent.
Sources: app/api/v1/analysis.py:118-124, app/api/v1/song_analysis.py:149-155
Summary
Analysis History Tracking provides a robust, secure, and paginated record of all mood classification activities within the MoodTune ecosystem. By utilizing Supabase for storage and Pydantic for validation, the system ensures that user data is isolated, indexed by time for quick access, and structured consistently across both playlist and song-level domains. This historical data forms the foundation for user features such as "Past Insights" and avoids redundant API costs or processing time.