FastAPI Backend Integration
Relevant source files
The following files were used as context for generating this wiki page:
The FastAPI Backend Integration represents the server-side infrastructure of the MoodTune application, responsible for computationally intensive tasks such as audio analysis using librosa. While the mobile frontend is built with Flutter and authentication is managed via Supabase, the Python-based FastAPI backend serves as the core engine for processing music data, managing Spotify integrations, and providing analysis history.
This integration facilitates the transition of raw audio data or third-party track identifiers into structured mood labels, confidence scores, and plain-language descriptors. It is hosted on the Railway platform and communicates with the mobile client through a RESTful API surface.
Sources: CLAUDE.md:6-9, README.md:47-51
System Architecture
The backend integration follows a service-oriented approach where the Flutter application acts as the primary consumer. The FastAPI server acts as a bridge between raw audio processing libraries, the Spotify API, and the application's data persistence layer.
High-Level Data Flow
The following diagram illustrates the interaction between the Flutter client, the FastAPI backend, and external services like Spotify and Supabase.
The diagram shows that while the client handles authentication directly with Supabase, the FastAPI backend performs the "heavy lifting" of audio processing and managed Spotify data retrieval.
Sources: CLAUDE.md:8-9, authplan.md:143-147
API Surface and Data Sources
The Flutter application interacts with the FastAPI backend through two primary data source objects: AnalysisRemoteDataSource and AudioUploadRemoteDataSource. A specialized SpotifyRepositoryImpl handles Spotify-specific logic.
Analysis Endpoints
The AnalysisRemoteDataSource handles requests related to song metadata analysis and historical data retrieval.
| Endpoint | Method | Description |
|---|---|---|
/analysis/analyze/{playlistId} | POST | Analyzes an entire Spotify playlist for mood trends. |
/analysis/history | GET | Retrieves a list of past analyses for authenticated users. |
/analysis/{id} | GET | Fetches details for a specific previous analysis. |
/song/analyze/{trackId} | POST | Analyzes a single Spotify track by its ID. |
Sources: CLAUDE.md:144-148
Audio Upload and Processing
For local files, the AudioUploadRemoteDataSource facilitates multipart uploads. The backend accepts files up to 15 MB in formats including MP3, M4A, FLAC, WAV, and OGG.
| Endpoint | Method | Format | Timeout (Connect/Send) |
|---|---|---|---|
/audio-upload/analyze | POST | multipart/form-data | 30s / 90s |
The backend uses librosa to extract musical features:
- Tempo: The speed of the track.
- Energy: The perceived intensity.
- Brightness: The harmonic frequency distribution.
- Texture: The timbral quality of the audio.
Sources: CLAUDE.md:130-132, CLAUDE.md:148, README.md:9-11
Spotify Integration
The SpotifyRepositoryImpl coordinates OAuth and profile data retrieval through the FastAPI backend.
| Endpoint | Description |
|---|---|
/spotify/authorize-url | Generates the URL for Spotify user consent. |
/spotify/connect | Finalizes the OAuth handshake. |
/spotify/connection | Checks the status of the current Spotify link. |
/spotify/profile | Retrieves Spotify user profile information. |
/spotify/playlists | Fetches the user's Spotify playlists for analysis. |
/spotify/disconnect | Removes the Spotify link from the user account. |
Sources: CLAUDE.md:149-150
Communication and Authentication
The backend requires secure communication, especially for features like history saving which is restricted to authenticated users.
Request Interception and Security
The mobile client uses a Dio HTTP client configured with a custom AuthInterceptor. This interceptor ensures that every request to the FastAPI backend includes a Supabase session token in the Authorization header.
If the backend returns a 401 Unauthorized response, the AuthInterceptor is designed to attempt a session refresh through Supabase before retrying the original request.
Sources: CLAUDE.md:43-45, authplan.md:95-103
Backend Environment Configuration
The backend's location is configurable via environment variables in the Flutter project. During development, it typically points to a local instance, while production points to the Railway deployment.
| Variable | Local Default | Production Example |
|---|---|---|
API_BASE_URL | http://127.0.0.1:8000/api/v1 | https://moodtune-backend.up.railway.app/api/v1 |
Sources: CLAUDE.md:139-142, README.md:70-74
Data Models and Results
The backend returns structured JSON responses that categorize music into one of four primary "mood identities."
Mood Identity Mapping
The analysis result includes a primary label and a confidence score.
| Identity | Description | Visual Palette |
|---|---|---|
| Upbeat | High energy, high brightness. | Distinct visual identity |
| Serene | Low energy, harmonic stability. | Distinct visual identity |
| Charged | High energy, aggressive texture. | Distinct visual identity |
| Reflective | Low energy, complex texture. | Distinct visual identity |
Confidence scores are categorized based on percentage:
- Strong: ≥75%
- Good: 50–74%
- Possible: <50%
Sources: README.md:28-32, README.md:34
Summary
The FastAPI backend integration is the analytical core of MoodTune. By offloading complex audio signal processing to a Python environment, the system provides sophisticated mood detection that would be prohibitive to perform directly on mobile hardware. The integration is secured via Supabase JWT validation and offers a comprehensive API for Spotify synchronization, file uploads, and historical data management.
Sources: CLAUDE.md:6-9, README.md:47-52