Supabase Integration

Relevant source files

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

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

Supabase serves as the primary backend-as-a-service (BaaS) for the MoodTune application, handling critical infrastructure components including Authentication and PostgreSQL database management. It provides a secure foundation for user identity, auto-saved analysis history, and mood filtering for authenticated users.

The integration follows a Clean Architecture approach, abstracting Supabase-specific logic within the Data Layer to ensure the Domain Layer remains independent of the framework. This setup enables features like email/password authentication, social OAuth (Google and Apple), and session persistence via secure token storage.

Sources: CLAUDE.md:8-10, README.md:21-23, authplan.md:12-25

Architectural Overview

The integration is partitioned across the standard Clean Architecture layers (Presentation, Domain, and Data). The supabase_flutter package is initialized during the application bootstrap process using project-specific environment variables.

Layered Responsibility

• Data Layer: Contains SupabaseAuthService (DataSource) and SupabaseAuthRepositoryImpl. This layer interacts directly with the Supabase SDK.
• Domain Layer: Defines the User entity and abstract AuthRepository interface, returning ResultFuture<T> (Either Failure or Success).
• Presentation Layer: Utilizes AuthBloc to manage state changes and trigger authentication flows.

Sources: CLAUDE.md:31-45, authplan.md:27-45

Component Relationship Diagram

The following diagram illustrates how Supabase components interact with the internal application architecture.

Authentication System

Supabase handles multiple authentication providers, including traditional email/password and modern OAuth flows. The system is designed to capture session tokens and securely persist them.

Supported Auth Methods

Method	Description	Source
Email/Password	Standard sign-up and sign-in via Supabase Auth.	authplan.md:154-170
Google Sign-In	OAuth flow using google_sign_in and Supabase signInWithIdToken.	authplan.md:172-195
Apple Sign-In	OAuth flow using sign_in_with_apple with name persistence on first login.	authplan.md:197-220
Guest Mode	Unauthenticated access allowed for basic mood analysis.	README.md:23-25

Token Management and Storage

The system uses a custom TokenStorage class (utilizing flutter_secure_storage) to handle JWTs. A key feature is the automatic chunking of tokens exceeding 3500 characters to bypass storage limitations.

• Storage: Tokens < 3500 chars are stored directly; larger tokens are chunked (3000 chars per chunk).
• Injection: A tokenProvider lambda in the DI container captures the current session token to pass to FastAPI data sources as a Bearer token.
• Interception: An AuthInterceptor automatically adds the Authorization: Bearer <token> header to requests and handles 401 Unauthorized responses by attempting a Supabase session refresh.

Sources: authplan.md:89-110, authplan.md:130-150, CLAUDE.md:95-98

Navigation and Auth States

The application's routing system, powered by go_router, is "auth-aware." It reacts to the Supabase authentication stream to enforce access control.

Data Models and Mapping

Internal application logic uses pure Dart entities, while the Supabase integration uses UserModel for data mapping.

User Mapping Logic

The _mapSupabaseUserToAppUser method converts Supabase User objects into the internal User entity:

• userId: Maps from supabaseUser.id.
• fullName: Extracted from userMetadata['full_name'], falling back to the email address.
• avatarUrl: Extracted from userMetadata['avatar_url'].
• emailVerified: Determined by checking if emailConfirmedAt != null.

Sources: authplan.md:243-255

Database Configuration

Variable	Purpose
SUPABASE_URL	The endpoint for the Supabase project.
SUPABASE_ANON_KEY	The anonymous public key for client-side requests.

Sources: CLAUDE.md:120-125, pubspec.yaml:45-50

Implementation Details

Initialization

Supabase is initialized in the bootstrap.dart file. Environment variables are passed to the Flutter app using --dart-define-from-file.

// Conceptual initialization based on authplan.md
await Supabase.initialize(
  url: 'YOUR_SUPABASE_URL',
  anonKey: 'YOUR_SUPABASE_ANON_KEY',
);

Sources: CLAUDE.md:12-18, authplan.md:315-320

Account Deletion

Account deletion requires coordination between the FastAPI backend and Supabase. The deleteAndLogoutUser flow calls a backend endpoint (DELETE /api/v1/users/me) before signing the user out of Supabase and clearing local TokenStorage.

Sources: authplan.md:231-241

Supabase integration provides a robust, scalable identity and data layer for MoodTune. By utilizing reactive auth streams and secure token management, the app ensures a seamless transition between guest and authenticated states while maintaining strict data security.