Database Structure
| Table | Purpose | Key Fields |
|---|---|---|
auth.users | Supabase built-in authentication | id, email, encrypted_password, email_confirmed_at |
public.user_profile | Application user profiles | user_id (FK), first_name, last_name, email, phone_number, country |
public.app_logs | Signup tracking and logging | id, user_id, log_type, message, origin |
Signup Flow
1User enters name, email, password, phone, country
2Pre-flight: check if email exists in user_profile
3Clean up any unlinked auth users via edge function
4Create auth.users record, send confirmation email
5Poll every 3s for email confirmation (max 5 min)
6Create user_profile, update local JSON, navigate home
Unlinked User Cleanup
The system automatically detects and removes orphaned auth users during signup:
1Check user_profile for email
2Try dummy sign-in with random password
3If
invalid_credentials: unlinked user found4Call
delete-unlinked-user edge functionSelf-healing: Unlinked user_profiles (no auth user) get their user_id updated with the new auth record.
Login Scenarios
| Scenario | User Experience | Backend |
|---|---|---|
| Valid Credentials | Immediate login to home | Auth token created, profile loaded |
| Wrong Password | "Invalid login credentials" | Supabase auth rejection |
| Unconfirmed Email | "Email not confirmed" | Auth blocked until confirmation |
| No Internet | Uses cached profile | Offline mode activated |
Password Reset
1Verify email exists in database
2Send password reset email
3User clicks link, enters new password
4Password updated, auto-login
Security Features
PasswordMin 6 chars, bcrypt encrypted
Email VerificationRequired, 24h expiry, 60s resend limit
SessionsJWT tokens, auto refresh, persistent
Rate Limiting60s email cooldown, Supabase login protection
Deep Linksio.lucidflow://login-callback
Offline ModeCached profiles, downloaded content playback
Data Storage
| Location | Data Stored |
|---|---|
| Supabase Database | auth.users credentials, public.user_profile, public.app_logs |
| SharedPreferences | user_id, is_new_user, cached_user_profile, pending_email |
| JSON Files | user_profile.json (subscription, courses, preferences, manifest) |
Implementation Files
| File | Purpose |
|---|---|
lib/screens/login_screen.dart | Login/Signup UI, form validation |
lib/screens/forgot_password_screen.dart | Password reset UI and flow |
lib/providers/user_provider.dart | State management, auth logic, profile caching |
lib/services/supabase_service.dart | Supabase API calls, unlinked user detection |
lib/models/user_profile.dart | User data model and JSON serialization |
supabase/functions/delete-unlinked-user/index.ts | Edge function for admin-level cleanup |