# ARCHITECTURAL CONSTRAINT: SUPABASE AUTHENTICATION & TOKEN MANAGEMENT

**CRITICAL RULE:** You are STRICTLY FORBIDDEN from implementing manual JWT refresh logic, manual token expiration checks, or custom 401 retry loops in `ApiService` or any other service.

**Context:**
The Supabase Flutter SDK (`supabase_flutter`) manages the session lifecycle, token refreshing, and persistence automatically. Previous attempts to manually refresh sessions created a race condition with the SDK, triggering Supabase's "Token Reuse Detection," which invalidates the user's entire session family and logs them out.

**Enforcement Guidelines:**

1.  **NO Manual Refreshes:**
    * Never call `supabase.auth.refreshSession()` manually inside API interceptors or service methods.
    * Never strictly check `session.expiresAt` before making a call. Trust the SDK to handle the header.
    * **Forbidden Pattern:** `if (tokenExpired) await refreshSession();`

2.  **NO Custom 401 Handling:**
    * Do not wrap API calls in `try/catch` blocks that specifically catch `401 Unauthorized` to attempt a re-login or refresh.
    * If a `401` occurs, allow the error to bubble up. The app's `AuthGate` (listening to the `onAuthStateChange` stream) will handle the logout naturally.

3.  **Required Initialization Pattern (`main.dart`):**
    * Always initialize Supabase with the PKCE flow to ensure stability on mobile.
    * **Code Standard:**
        ```dart
        await Supabase.initialize(
          url: ...,
          anonKey: ...,
          authOptions: const FlutterAuthClientOptions(
            authFlowType: AuthFlowType.pkce, // MANDATORY
            autoRefreshToken: true,
          ),
        );
        ```

4.  **Required Edge Function Call Pattern (`api_service.dart`):**
    * Use the SDK's `functions.invoke` method. It automatically injects the correct, fresh Bearer token.
    * **Code Standard:**
        ```dart
        // DO THIS:
        final response = await _supabase.functions.invoke('function-name', ...);

        // DO NOT DO THIS:
        // final token = _supabase.auth.currentSession.accessToken;
        // final response = http.post(..., headers: {'Authorization': 'Bearer $token'});
        ```

5.  **State Management (`auth_provider.dart`):**
    * User state must always be derived reactively from `supabase.auth.authStateChanges`. Never rely on a static `User?` variable that might become stale.

**Correction Protocol:**
If you encounter code that violates these rules (e.g., variables like `_refreshCooldown` or `_refreshInFlight`), **DELETE IT IMMEDIATELY** and refactor to use the standard SDK methods.