# Mobile Auth Flow & Session Management

This document outlines the client-side user verification, authentication routing, SharedPreferences token storage, and account deletion flows in the mobile application.

---

## 1. Authentication Screens Flow

```mermaid
stateDiagram-v2
    [*] --> MobileScreen : Enter Mobile Number
    MobileScreen --> OTPScreen : Not Verified (New Registration / Unverified)
    OTPScreen --> ProfileFillScreen : OTP Correct, filling Profile info
    ProfileFillScreen --> PinVerification : PIN Set (Navigate to Dashboard)
    MobileScreen --> PinVerification : Verified User (Login flow)
    PinVerification --> HomeDashboard : PIN Correct
```

---

## 2. PIN verification & Local Session Storage

* **Verification:** The client sends the 10-digit mobile number and PIN payload to the `/api/login-pin-verification` API.
* **Lockout Response:** If a user makes 5 failed attempts, the server will block further verification calls for 15 minutes. The app displays the returned warning message: `"Too many incorrect PIN attempts. Your account is locked for 15 minutes."` and locks the PIN input keyboard during the lock duration.
* **Token Storage:** Upon successful verification, the backend returns a unique `apptoken`. The app stores this token locally using **SharedPreferences** to persist the user's session:
  ```dart
  final prefs = await SharedPreferences.getInstance();
  await prefs.setString('apptoken', token);
  ```

---

## 3. Logout Workflow

When the user taps the Logout button:
1. The app calls the logout API: `/api/user-logout` to clear the token on the server.
2. Locally, the client cleans up the storage and resetting variables inside `AuthProvider`:
   ```dart
   _isAuth = false;
   token = '';
   _dataProvider.clearProvider();
   _contestProvider.clearProvider();
   ```
3. Navigates the user back to the Auth Login screen.

---

## 4. User Account Deletion Flow

When the user requests to delete their account:
1. The client prompts the user to enter their PIN for verification.
2. Sends the request to the backend: `/api/user-account-delete`.
3. If successful, the app clears the local cache, clears user preferences, resets providers, and immediately navigates back to the Login screen:
   ```dart
   if (response['status'] == "1") {
     Utils.scaffoldMessage(response['msg']);
     _isAuth = false;
     _dataProvider.clearProvider();
     _contestProvider.clearProvider();
     fcmToken = '';
     // Clear SharedPreferences and redirect to Login
   }
   ```
This prevents stale profiles or home screen data from remaining visible on the screen.