DocHub
DocHub/Hypnoelp App/Authentication System/Login & Password Reset
Login scenarios, password reset flow, deep links, and offline mode

Login & Password Reset

Login Scenarios

Scenario User Experience Backend Process
Valid Credentials Immediate login and redirect to home Auth token created, user profile loaded
Invalid Email Error: “Please enter a valid email” Validation fails client-side
Wrong Password Error: “Invalid login credentials” Supabase auth rejection
Unconfirmed Email Error: “Email not confirmed” Auth blocked until confirmation
No Internet Uses cached profile if available Offline mode activated
Unlinked Auth User Signup appears to fail initially Automatic cleanup then fresh signup succeeds
Unlinked User Profile Signup succeeds normally Self-healing: updates existing profile with new auth ID

Debouncing & Duplicate Prevention

  • Tracks last authenticated user ID and timestamp
  • Ignores duplicate auth changes within 2 seconds
  • Prevents multiple navigation attempts
  • Ensures stable authentication flow

Password Reset Flow

  1. Email Verification: System checks if email exists in database
  2. Send Reset Link: If email exists, sends password reset email
  3. User Clicks Link: Opens reset form in browser
  4. New Password Entry: User enters new password (min 6 characters)
  5. Password Update: Updates in auth.users table
  6. Auto Login: User automatically signed in with new password

Password Reset Errors

Error Message
Email not found “This account is not currently registered”
Rate limit exceeded “Too many requests, please wait 60 seconds”
Same password “New password must be different from old password”
Platform Deep Link Format Usage
Android io.lucidflow://login-callback Email confirmation redirect
iOS (future) io.lucidflow://login-callback Email confirmation redirect
Web (future) https://hypno-56118.web.app/ Standard web URLs

Offline Mode

When the device has no internet connection:

Available offline:

  • Access previously loaded user profile
  • Play downloaded audio content
  • View course information

Requires internet:

  • New purchases
  • Account settings changes
  • Sync operations

Welcome Flow for New Users

  1. New user completes sign-up
  2. is_new_user flag set to true
  3. Free trial plan automatically assigned
  4. Welcome dialog shown on first login
  5. Onboarding guide available

Implementation Files

File Purpose
lib/screens/login_screen.dart Login UI and form validation
lib/screens/forgot_password_screen.dart Password reset UI and flow
lib/providers/user_provider.dart Auth logic, profile caching
lib/models/user_profile.dart User data model and JSON serialization