# Application Flow for Mitra App
We are defining mitra flow along with the app referenced on the claude design

## A. Pre-Home (auth)

The mitra app has no Google/Apple login — phone OTP only. All limits live on the
backend (see `backend/src/services/otp.service.js` + `config.service.js`); the
app must surface them clearly so a stuck mitra knows what to do.

### A1. Boot — token gate
1. App boot → check stored refresh token
   1. Valid session → go straight to Home (skip auth)
   2. No / expired refresh → go to Login screen

### A2. S3a · Input WhatsApp
1. Show phone number field (E.164, hint `+628xxxxxxxxxx`)
2. "Kirim OTP" submit → `POST /api/mitra/auth/otp/request`
3. Error responses:
   1. `PHONE_INVALID` (422) → inline field error "Format nomor salah"
   2. `OTP_COOLDOWN` (429) → snackbar "Tunggu N detik sebelum minta kode baru" using `retry_after_seconds`
   3. `OTP_RATE_LIMIT_PHONE` (429) → popup "Terlalu banyak permintaan untuk nomor ini. Coba lagi dalam N menit" (use `retry_after_seconds`)
   4. `OTP_RATE_LIMIT_IP` (429) → popup "Terlalu banyak permintaan dari jaringan ini. Coba lagi nanti / hubungi admin"
4. Success → push OTP screen with `otp_request_id` + masked phone

### A3. S3b · OTP verification (6-digit)
1. Show 6 digit fields + masked phone reminder
2. Auto-submit when 6 digits entered → `POST /api/mitra/auth/otp/verify`
3. Show "Tersisa N percobaan" hint when attempts have been used (compute from local counter; backend doesn't expose it)
4. Show "Kirim ulang kode" button — disabled until 60s cooldown elapses, with countdown timer
5. Error responses:
   1. `CODE_INVALID` (422) → inline "Kode harus 6 digit angka"
   2. `CODE_MISMATCH` (401) → clear fields, inline "Kode salah · tersisa N percobaan", focus first digit
   3. `OTP_ATTEMPTS_EXCEEDED` (429) → blocked popup "Terlalu banyak percobaan" with CTAs: "Minta kode baru" (back to Login) / "Hubungi admin"
   4. `OTP_EXPIRED` (410) → popup "Kode kadaluarsa" → CTA "Minta kode baru" (back to Login pre-filled)
   5. `OTP_USED` (409) → same as `OTP_EXPIRED` (treat as terminal — user must request a new code)
   6. `WRONG_FLOW` (400) → popup "Kode ini bukan untuk akun mitra. Pastikan kamu pakai app yang benar"
   7. `ACCOUNT_INACTIVE` (403) — comes from verify endpoint after a valid code, before token issuance → full-screen "Akun belum aktif" state with admin contact CTAs (WhatsApp / Telegram). No retry.
6. Success → store tokens → push Home

### A4. Resend OTP (from S3b)
1. From S3b → tap "Kirim ulang kode" (only enabled after 60s)
2. Hits same `POST /api/mitra/auth/otp/request` → new `otp_request_id` replaces old
3. Resets the local attempts counter to 0
4. Same error scenarios as A2 (cooldown / rate-limit) apply

## B. Home onwards

mitra app flow:
1. Home screen
2. Undangan CTA -> Show Undangan · pending invitations
3. Perpanjang CTA -> Show Undangan · Perpanjang Curhat
4. Profil CTA -> show Bestie Profile · profil
2. Status Offline?
    1. Status offline -> Show Bestie Home · OFFLINE
    2. Status online -> Show Bestie Home · standby & status. Goto next step

3. incoming chat request:
    1. New chat -> Show Popup · incoming Curhat Baru
    2. Extend chat -> Show Popup · incoming Perpanjang

4. Accept chat request?
    1. Reject -> Close dialog and Go to hoome screen
    2. Accept -> Show Bestie Chat Room · sesi aktif

5. Session end -> Bestie Chat · durasi habis