Spotify Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Spotify Integration in MoodTune enables authenticated users to connect their Spotify accounts to the application for mood-based analysis of their personal music library. While MoodTune provides a "Guest Mode" for analyzing individual audio uploads and Jamendo tracks, the Spotify integration serves as the primary entry point for authenticated users to interact with their existing playlists and profile data.
Sources: CLAUDE.md:8-12, README.md:14-26
This system is built using a Clean Architecture approach, leveraging a FastAPI backend to interface with Spotify's API and Supabase for session management. The integration allows users to retrieve their Spotify profile, list playlists, and submit specific playlists or tracks for audio feature extraction and mood categorization.
Sources: CLAUDE.md:65-72, README.md:57-64
Architecture and Components
The Spotify integration is housed within the lib/features/spotify/ directory and follows the project's standard Clean Architecture pattern. It is divided into three distinct layers: Data, Domain, and Presentation.
Sources: CLAUDE.md:73-81
Feature Layer Breakdown
| Layer | Responsibilities | Key Components |
|---|---|---|
| Presentation | Manages UI state and user interactions. | SpotifyBloc, Spotify Views, Playlist Widgets |
| Domain | Contains business logic and repository contracts. | SpotifyRepository (interface), Use Cases |
| Data | Handles external communication and data mapping. | SpotifyRepositoryImpl, SpotifyRemoteDataSource |
Sources: CLAUDE.md:82-94
Data Flow for Spotify Operations
The following diagram illustrates the flow of a Spotify request, such as fetching user playlists, through the Clean Architecture layers.
The application uses the SpotifyBloc as a global provider to maintain the connection state and loaded data across different screens.
Sources: CLAUDE.md:95-103
Backend API Surface
The Flutter application communicates with a FastAPI backend that acts as a proxy for Spotify's OAuth and data endpoints. The SpotifyRepositoryImpl interacts with these endpoints to manage the lifecycle of a Spotify connection.
Spotify Endpoints
| Endpoint | Method | Description |
|---|---|---|
/spotify/authorize-url | GET | Generates the initial Spotify OAuth authorization URL. |
/spotify/connect | POST | Finalizes the connection using the OAuth code. |
/spotify/connection | GET | Checks the current status of the Spotify link. |
/spotify/profile | GET | Fetches the user's Spotify profile (display name, images). |
/spotify/playlists | GET | Retrieves a list of the user's Spotify playlists. |
/spotify/disconnect | POST | Removes the Spotify link from the user's account. |
Sources: CLAUDE.md:141-149
Authentication and Security
Spotify integration is strictly restricted to authenticated users. The AppRouter configuration ensures that the Spotify flow starts at the /spotify route, which is protected by Supabase authentication guards.
Sources: CLAUDE.md:118-124, routing_plan.md:385-400
Token Management
- Bearer Auth: All requests to the Spotify backend endpoints include a Supabase session token passed via an
AuthInterceptor. - Session Capture: The
tokenProviderin the dependency injection setup captures the token at call time to ensure the backend can verify the user's identity before making Spotify API calls on their behalf. - Secure Storage: While Supabase tokens are handled by the core auth system, the application ensures that no raw Spotify tokens are stored client-side; the backend manages the Spotify OAuth tokens.
Sources: CLAUDE.md:112-117, authplan.md:105-120
Navigation and Routing
Navigation to Spotify-related features is managed via GoRouter. The system utilizes a StatefulShellRoute to maintain the state of Spotify-related tabs, such as the playlist browser and analysis history.
Sources: routing_plan.md:465-490, CLAUDE.md:118-121
Route Implementation Details
The Spotify feature is integrated into the MaterialApp using AppRouter.router. Access is controlled by the redirect logic in the router, which redirects unauthenticated users to the onboarding flow if they attempt to access protected Spotify routes.
Sources: routing_plan.md:530-550
Conclusion
The Spotify Integration provides the core functional value for registered MoodTune users, enabling seamless analysis of their music libraries. By offloading the complex OAuth and audio processing logic to a FastAPI backend while maintaining a strict Clean Architecture on the Flutter client, the system ensures a responsive and secure user experience.
Sources: README.md:1-12, CLAUDE.md:50-55