Analysis History & Auto-saving

Relevant source files

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

• README.md
• CLAUDE.md
• authplan.md
• routing_plan.md
• pubspec.yaml

Introduction

Analysis History and Auto-saving are core features of MoodTune that allow authenticated users to persist and revisit their music mood analysis results. While guest users can perform analyses, only users authenticated via Supabase benefit from automatic persistence to the backend database. This system tracks audio features like tempo, energy, and texture to provide consistent historical insights.

The system is architected using Clean Architecture, ensuring that the logic for fetching history and auto-saving results is decoupled from the UI. History is capped at the 50 most recent analyses and includes filtering capabilities by mood identity (Upbeat, Serene, Charged, Reflective).
Sources: README.md:1-25, CLAUDE.md:43-55

System Architecture & Data Flow

The history system relies on a multi-layered approach involving the AnalysisBloc, AnalysisRemoteDataSource, and the FastAPI backend. When an analysis is triggered, the result is automatically saved to the Supabase/PostgreSQL database if a session token is present.

Data Flow Diagram

The following diagram illustrates the flow from a user request to the persistent storage of analysis history.

Components and Responsibilities

Component	Responsibility
AnalysisBloc	Manages states for playlist/song analysis and history retrieval.
AnalysisRemoteDataSource	Handles HTTP communication with the backend history endpoints.
Supabase	Provides the PostgreSQL database for persistent storage of user analyses.
AuthInterceptor	Injects the Bearer token required to access user-specific history.
Sources: CLAUDE.md:78-85, authplan.md:95-107

API Implementation

The AnalysisRemoteDataSource interacts with specific FastAPI endpoints to manage the history lifecycle. These endpoints are protected and require a valid Supabase session token.

History API Endpoints

Endpoint	Method	Description
/analysis/history	GET	Retrieves the list of past analyses for the authenticated user.
/analysis/{id}	GET	Fetches full details for a specific historical analysis record.
/analysis/analyze/{id}	POST	Performs a new analysis which is automatically saved to history.
Sources: CLAUDE.md:129-135

Sequence of Auto-saving

Auto-saving occurs as a side effect of the analysis process. The AnalysisBloc handles the transition from a loading state to a success state, at which point the backend has already persisted the record.

Presentation and Filtering

Historical data is displayed on a dedicated History Screen, accessible only to authenticated users. This screen supports filtering based on the four mood identities defined in the app.

Navigation and Access

Access to the history feature is managed by the AppRouter and GoRouter. The history route is part of a StatefulShellRoute, allowing it to maintain its state and scroll position independently of the main home/analysis view.
Sources: routing_plan.md:128-155, README.md:28-40

• Route Name: /history (defined in RouteNames)
• Access Control: Guarded by redirect logic in AppRouter that checks isAuthenticated().
• State Management: Uses BlocProvider.value to provide the AnalysisBloc to the history view.
  Sources: routing_plan.md:200-215, routing_plan.md:580-610

Implementation Details

The persistence layer uses Dio with a specialized configuration for timeouts and authentication injection.

// Example of how History is retrieved in the Data Layer
// Derived from AnalysisRemoteDataSource patterns
final response = await _dio.get('/analysis/history');
return (response.data as List)
    .map((json) => AnalysisModel.fromJson(json).toDomain())
    .toList();

Sources: CLAUDE.md:58-65, CLAUDE.md:120-125

Conclusion

The Analysis History & Auto-saving feature provides high value to returning users by leveraging Supabase for secure data persistence. By integrating the history retrieval into the AnalysisBloc and protecting the routes via GoRouter redirects, the app ensures that user data is only accessible to authorized individuals while maintaining a seamless, "auto-saved" experience.