Authentication System

The Authentication System in MoodTune is a robust, multi-provider framework built on Supabase. It follows Clean Architecture principles to manage user identities, secure session tokens, and coordinate access across the mobile application. While the app allows guest access for basic music analysis, authenticated users benefit from features like auto-saved history and mood filtering. Sources: README.md:9-11, authplan.md:12-16

The system integrates directly with Supabase for email/password authentication and leverages OAuth providers for Google and Apple sign-ins. It is designed to be reactive, utilizing a global AuthBloc and a specialized AuthInterceptor to handle token lifecycle and session refreshes transparently. Sources: CLAUDE.md:29-32, authplan.md:104-162

Architectural Overview

The system is partitioned into three distinct layers to ensure separation of concerns and testability. Sources: authplan.md:18-32

Layered Structure

• Presentation Layer: Manages UI components and state via AuthBloc. Sources: CLAUDE.md:68-71, authplan.md:264-270
• Domain Layer: Contains business logic through Use Cases (e.g., LoginUseCase, GoogleSignInUseCase) and defines the AuthRepository interface. Sources: authplan.md:214-232, CLAUDE.md:47-50
• Data Layer: Implements the repository, manages data models (UserModel), and interfaces with external services like SupabaseAuthService and TokenStorage. Sources: authplan.md:88-102, CLAUDE.md:42-45

Data Flow Diagram

The following diagram illustrates the flow of authentication data from the UI through the architecture to the external Supabase service.

Core Components

Token Management and Storage

The system employs a TokenStorage class to manage JWTs securely. It uses flutter_secure_storage for encrypted persistence and includes a unique chunking mechanism to handle tokens exceeding 3500 characters, ensuring compatibility across different mobile keychain limits. Sources: authplan.md:66-86, pubspec.yaml:32

Supabase Integration

SupabaseAuthService is the primary interface for authentication operations. It maps Supabase User objects to the application's internal User entity to decouple the domain from the infrastructure. Sources: authplan.md:104-190

Authentication Methods

The system supports four primary authentication flows. Sources: authplan.md:118-175

1. Email and Password

Standard sign-up and sign-in flows. The service extracts the access token from the Supabase session upon successful authentication. Sources: authplan.md:118-129

2. Google Sign-In

Uses the google_sign_in package to obtain an idToken, which is then passed to Supabase's signInWithIdToken method. This requires specific configuration for serverClientId (Web) and clientId (iOS). Sources: authplan.md:131-144, pubspec.yaml:33

3. Apple Sign-In

Utilizes sign_in_with_apple. A unique requirement here is that Apple only provides the user's name on the first sign-in; the system must upsert this to a user_profiles table to persist it. Sources: authplan.md:146-162, pubspec.yaml:34

4. Guest Mode

Users can access the "Analysis" features without an account. However, history persistence is only enabled once the user authenticates. Sources: README.md:17-18, routing_plan.md:209-215

Routing and Security Guards

Authentication state is tightly integrated with the navigation system via go_router. Sources: routing_plan.md:21-36

Authentication-Aware Redirects

The AppRouter uses a refreshListenable tied to the Supabase authStateChanges stream. This allows the application to automatically redirect users based on their login status. Sources: routing_plan.md:195-215

Route Protection Summary

Conclusion

The Authentication System for MoodTune provides a secure and scalable foundation for user management. By combining Clean Architecture with Supabase's identity platform and a reactive routing system, it ensures that sensitive tokens are handled correctly and that user state is consistently reflected across the application UI. Sources: authplan.md:323-333