Introduction to MoodTune
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune is a mobile application developed with Flutter that provides instant song mood analysis. By leveraging librosa-based audio analysis on a FastAPI backend, the app evaluates musical characteristics such as tempo, energy, brightness, and texture to return a primary mood label and a detailed explanation of the track's emotional profile. Users can analyze uploaded audio files or browse the free Jamendo music catalog without requiring an account, though authenticated users gain access to enhanced features like auto-saved history and mood-based filtering.
The application is architected using Clean Architecture principles, ensuring a strict separation between Presentation, Domain, and Data layers. It utilizes Supabase for authentication and PostgreSQL database management, providing a robust foundation for secure user data handling and session persistence.
Sources: README.md:3-11, CLAUDE.md:12-14, CLAUDE.md:38-41
Core Feature Overview
MoodTune centers on four distinct mood identities: Upbeat, Serene, Charged, and Reflective. Each identity corresponds to a specific visual theme and color palette within the UI.
Key Capabilities
| Feature | Description |
|---|---|
| Mood Analysis | Analyzes MP3, M4A, FLAC, WAV, and OGG files (up to 15 MB) in approximately 30 seconds. |
| Confidence Scoring | Provides a match quality rating: Strong (≥75%), Good (50–74%), or Possible (<50%). |
| Music Catalog | Integration with Jamendo API v3 for browsing and analyzing tracks without manual uploads. |
| Guest Mode | Allows full analysis features without an account wall; authentication is optional. |
| History | Auto-saves results for authenticated users, capped at 50 analyses. |
Sources: README.md:15-28, README.md:50
System Architecture
The project follows a Clean Architecture structure where dependencies point inward toward the Domain layer.
The architecture ensures that the Domain layer remains pure Dart, free from framework dependencies or external logic.
Sources: CLAUDE.md:38-41, authplan.md:15-30
Technology Stack
- Mobile Framework: Flutter (Dart) for iOS and Android.
- Backend: FastAPI (Python) hosted on Railway.
- Audio Processing: librosa (Python).
- Authentication & Database: Supabase (PostgreSQL).
- Networking: Dio with custom interceptors for auth and logging.
- State Management: BLoC (Business Logic Component).
Sources: README.md:46-52, pubspec.yaml:12-30, CLAUDE.md:42-53
Data and API Flow
MoodTune interacts with multiple data sources, primarily the FastAPI backend and Supabase Auth.
Analysis Sequence
The following diagram illustrates the flow of an audio analysis request from the mobile client to the backend processing service.
Sources: CLAUDE.md:73-82, CLAUDE.md:115-119, README.md:15-17
Authentication and Security
The authentication system is managed via Supabase and supports multiple entry points, including Email/Password, Google, and Apple Sign-In.
Token Management
To maintain security, the app implements a TokenStorage utility that uses FlutterSecureStorage. It includes a chunking mechanism for large tokens (exceeding 3500 characters) to ensure compatibility across different mobile keychain implementations.
Auth Interceptor Logic
A central AuthInterceptor is used in the Dio HTTP client to automatically inject the Supabase session token into backend requests.
Navigation and Routing
Navigation is handled declaratively using go_router, with an AppRouter providing centralized control over route definitions and authentication guards.
Route Structure
The app uses a StatefulShellRoute for the main navigation tabs (Home and History), ensuring that scroll positions and navigation stacks are preserved when switching between features.
| Route Constant | Path | Accessibility |
|---|---|---|
initial | / | Public |
onboarding | /onboarding | Public |
login | /login | Public |
home | /home | Authenticated/Guest |
history | /history | Authenticated Only |
Sources: routing_plan.md:30-50, routing_plan.md:135-150, CLAUDE.md:98-102
Conclusion
MoodTune is a technically sophisticated audio analysis tool that combines modern mobile development practices with specialized backend signal processing. By utilizing a Clean Architecture and a robust authentication/routing infrastructure, the project maintains high scalability and developer clarity. The integration of guest-first analysis with authenticated cloud history provides a flexible user experience tailored for both casual listeners and music enthusiasts.