Supabase Integration

Relevant source files

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

• src/core/services/api/supabase.client.js
• SUPABASE_KEY_SETUP.md
• src/core/services/api/auth.api.js
• src/core/config/env.config.js
• TASK_4_SUMMARY.md
• src/core/services/api/sync.api.js
• SECURITY_AND_CLEANUP_FIXES.md

The Supabase integration provides the backend-as-a-service (BaaS) for the eefashiondesign application. It is responsible for handling user authentication, session management, and is architected to support future features like cloud data synchronization and file storage. The integration is designed to be robust, with clear separation of concerns between client setup, configuration, and API services.

The system uses a centralized Supabase client and wraps its functionality in dedicated API modules, such as auth.api.js for authentication and sync.api.js for data persistence. This modular approach allows features to be enabled or disabled via configuration and provides a "future-proof" architecture with placeholders for upcoming functionality.

Architecture Overview

The integration is composed of several key files that work together to connect the application to the Supabase backend.

This diagram shows the dependency flow from UI components down to the Supabase backend, highlighting the central role of supabase.client.js and env.config.js.
Sources: TASK_4_SUMMARY.md, src/core/services/api/auth.api.js, src/core/services/api/supabase.client.js

Configuration and Initialization

The connection to Supabase is managed through environment variables defined in src/core/config/env.config.js. The Supabase client is initialized in src/core/services/api/supabase.client.js, which reads these configuration values.

Environment Variables

The following variables in env.config.js are crucial for the Supabase integration.

Variable	Description	Default Value
SUPABASE_URL	The unique URL for the Supabase project.	https://riwzkjsbnggcmqnjimsa.supabase.co
SUPABASE_PUBLISHABLE_KEY	The public "anon" key for the project. Safe for client-side use.	sb_publishable_L89YcNI2LfXVM1ItoJlSOg_d_CdMrit

Sources: src/core/config/env.config.js:16-22

Initialization Flow

The client initialization includes validation steps to ensure the configuration is correct, especially during development.

This flow shows how environment variables are loaded and validated before the Supabase client is created and exported for use in other services.
Sources: src/core/services/api/supabase.client.js:8-12, src/core/config/env.config.js:40-70

Key Setup

The project has specific requirements for the SUPABASE_PUBLISHABLE_KEY. An incorrect key format will cause authentication to fail. The documentation explicitly warns against using the placeholder sb_publishable_... key and instructs the developer to use the real JWT-formatted anon key from the Supabase dashboard.

Sources: SUPABASE_KEY_SETUP.md, src/core/config/env.config.js:51-57

Supabase Client (supabase.client.js)

This file is the cornerstone of the integration, creating and exporting a single, shared Supabase client instance.

Client Instantiation

The client is created with specific options for authentication handling:

// src/core/services/api/supabase.client.js:28-35
export const supabase = createClient(supabaseUrl, supabasePublishableKey, {
  auth: {
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
    storage: undefined, // Use default AsyncStorage
    storageKey: 'eefashionita-auth-token',
  },
});

• autoRefreshToken: Automatically refreshes the auth token to keep the user logged in.
• persistSession: Persists the user's session across app launches using AsyncStorage.
• storageKey: A custom key for storing the session data.

Sources: src/core/services/api/supabase.client.js:28-35

Helper Functions

The module also exports several utility functions for checking the client's status and retrieving user data.

Function	Description
isSupabaseConfigured()	Checks if the Supabase URL and key are valid and not placeholders.
getCurrentSession()	Asynchronously retrieves the current user session from Supabase.
getCurrentUser()	Asynchronously retrieves the current user object from Supabase.

Sources: src/core/services/api/supabase.client.js:46-77

Authentication API (auth.api.js)

This module provides a comprehensive API for all user authentication operations, acting as a wrapper around the Supabase client. It handles different key formats and provides user-friendly error messages.

Key Functions

Function	Description
signUp(email, password, metadata)	Registers a new user.
signIn(email, password)	Signs in an existing user.
signOut()	Signs out the current user and clears local session data.
getSession()	Retrieves the current session, with a fallback to AsyncStorage.
getCurrentUser()	Retrieves the current user object.
updateProfile(updates)	Updates the current user's metadata.
resetPassword(email)	Sends a password reset email to the user.
onAuthStateChange(callback)	Subscribes to authentication state changes (e.g., SIGNED_IN, SIGNED_OUT).

Sources: src/core/services/api/auth.api.js

Authentication Flow (Sign In)

The signIn function has special logic to handle both new (sb_...) and legacy (JWT) Supabase keys. For new keys, it makes a direct fetch call to the Supabase token endpoint.

This diagram illustrates the sign-in process when a new publishable key format is used, bypassing the standard supabase.auth.signInWithPassword method.
Sources: src/core/services/api/auth.api.js:134-164, src/core/services/api/auth.api.js:239-251

Error Handling

The auth.api.js module includes logic to parse errors from Supabase and return more user-friendly messages. For example, it translates "Invalid login credentials" into "Invalid email or password. Please try again."

// src/core/services/api/auth.api.js:280-285
let errorMessage = error.message;
if (error.message.includes('Invalid login credentials')) {
  errorMessage = 'Invalid email or password. Please try again.';
} else if (error.message.includes('Email not confirmed')) {
  errorMessage = 'Please verify your email address before signing in.';
}

Sources: src/core/services/api/auth.api.js:203-214, 280-287

Cloud Sync API (sync.api.js)

This file serves as a placeholder for future cloud synchronization features. It defines a set of functions that are ready to be implemented when the feature is enabled.

Placeholder Functions

The API is currently disabled by the FEATURES.CLOUD_SYNC.ENABLED flag and all functions return a "Not implemented yet" error.

Function	Description
syncDesignToCloud(designId, designData)	Upserts a design to the designs table in the cloud.
loadDesignFromCloud(designId)	Loads a specific design from the cloud.
getAllDesignsFromCloud()	Fetches all designs belonging to the current user.
deleteDesignFromCloud(designId)	Deletes a design from the cloud.

The file contains commented-out example implementations using the Supabase client, demonstrating how the feature will eventually work.
Sources: src/core/services/api/sync.api.js, TASK_4_SUMMARY.md

Security

Security is a key consideration in the integration.

• Key Exposure: The codebase and documentation repeatedly warn against committing real API keys to Git. The .env file, intended for local secrets, is correctly listed in .gitignore.
• Client-Side Keys: The integration correctly uses the public anon key, which is safe for client-side exposure, and explicitly warns against using the service_role key.
• Key Rotation: A security document, SECURITY_AND_CLEANUP_FIXES.md, instructs the user to rotate Supabase keys if they have been accidentally exposed.

Sources: src/core/config/env.config.js:7-15, SECURITY_AND_CLEANUP_FIXES.md, SUPABASE_KEY_SETUP.md