# New NextGate Auth & Onboarding Flow UI (DEPRECATED) ## 1. Sign Up Flow ### Path A: Phone User ``` Enter phone number │ ▼ Verify OTP │ ▼ Enter age & name │ ▼ Pick username │ ▼ Pick interests (min 3) │ ▼ Profile setup (optional) │ ▼ Home Feed 🎉 (device registered) ── Post-onboarding ── Soft nudge to add email (banner only, never blocking) ``` ### Path B: Email User ``` Enter email address │ ▼ Verify OTP │ ▼ Enter age & name │ ▼ Pick username │ ▼ Verify phone number ← REQUIRED (Identity) │ ▼ Pick interests (min 3) │ ▼ Profile setup (optional) │ ▼ Home Feed 🎉 (device registered) ``` ### Path C: Google / Apple OAuth ``` Tap Google / Apple │ ▼ OAuth authorize │ ▼ Enter age & name (pre-filled from OAuth) │ ▼ Pick username (suggestions from name) │ ▼ Verify phone number ← REQUIRED (Identity) │ ▼ Pick interests (min 3) │ ▼ Profile setup (optional) (profile pic pre-filled) │ ▼ Home Feed 🎉 (device registered) ``` --- ## 2. Onboarding Steps Detail ### Step Summary | # | Step | Applies To | Endpoint | |---|------|-----------|----------| | 0 | OTP / OAuth entry | All | `/auth/start` + `/auth/verify` or `/auth/login/oauth` | | 1 | Age & name | All | `/auth/onboarding/age` | | 2 | Username | All | `/auth/onboarding/username` | | 3 | Contact verify (PHONE) | Email + OAuth only | `/auth/onboarding/contact/initiate` + `/contact/verify` | | 4 | Interests | All | `/auth/onboarding/interests` | | 5 | Profile | All | `/auth/onboarding/profile` | ### Contact Verification Rule | Signup Method | Required Contact | Reason | |---------------|-----------------|--------| | Phone | ~~Email~~ (optional, post-onboarding) | Phone = real identity, M-Pesa already linked | | Email | Phone (blocking) | Needed for M-Pesa payments | | Google / Apple | Phone (blocking) | OAuth gives email, phone still required for payments | ### Onboarding Step Sequence **Phone user:** ``` INITIATED → OTP_VERIFIED → AGE_VERIFIED → USERNAME_SET → INTERESTS_SELECTED → PROFILE_COMPLETED → COMPLETED ``` **Email / OAuth user:** ``` INITIATED → OTP_VERIFIED → AGE_VERIFIED → USERNAME_SET → CONTACT_VERIFIED → INTERESTS_SELECTED → PROFILE_COMPLETED → COMPLETED ``` ### Token Expiry | Token | Expiry | Purpose | |-------|--------|---------| | `onboardingToken` | 7 days | Active onboarding flow, resets each step | | `onboardingRefreshToken` | 30 days | Safety net if token expires mid-flow | | `accessToken` | Configured | Normal app access | | `refreshToken` | Configured | Access token rotation | --- ## 3. Contact Verification — Inline UX (3 states, 1 page) ``` STATE A — Input ┌──────────────────────────────────────┐ │ 📱 Add your phone number │ │ │ │ Your email j••••@g••••.com ✅ │ │ │ │ We need your phone for: │ │ • Offline notifications │ │ • Account security & recovery │ │ │ │ Phone: [+255______________] │ │ [Send Code →] │ └──────────────────────────────────────┘ STATE B — OTP Input ┌──────────────────────────────────────┐ │ Enter code sent to ••• ••• ••50 │ │ │ │ [_] [_] [_] [_] [_] [_] │ │ │ │ [Edit number] Resend (60s) │ └──────────────────────────────────────┘ STATE C — Edit (tapping [Edit number] transforms inline) ┌──────────────────────────────────────┐ │ New number: [+255______________] │ │ [Send new code →] [Cancel] │ └──────────────────────────────────────┘ ``` > Previous OTP invalidated immediately on edit. > No page navigation — single page, three inline states. --- ## 4. Login Flow ### Identifier Detection | Input pattern | Detected as | |---------------|-------------| | Starts with `+` | Phone | | Contains `@` + domain | Email | | Otherwise | Username | ### Complete Login Flow ``` ┌─────────────────────────────────────┐ │ Login Screen │ └─────────────────┬───────────────────┘ │ ┌───────────┼───────────┐ │ │ │ ▼ ▼ ▼ Google/ Phone/Email Username Apple │ │ │ │ │ ▼ ▼ ▼ OAuth Detect Find account │ account │ │ │ │ │ ▼ ▼ │ Has password? Show masked │ │ OTP destination │ ┌─────┴─────┐ │ │ ▼ ▼ │ │ No Yes │ │ │ │ │ │ │ ┌─────┴─────┐ │ │ │ ▼ ▼ │ │ │ [OTP] [Password] │ │ │ │ │ │ ▼ ▼ ▼ │ │ OTP Screen Password │ │ │ Screen │ │ │ │ │ │ └─────┬─────┘ │ │ │ │ ▼ ▼ ▼ Device Check Device Check OTP Screen │ │ │ ▼ ▼ ▼ (see §5) (see §5) Device Check │ ▼ (see §5) ``` --- ## 5. Device Trust Check ### After Authentication ``` User Authenticated │ ▼ ┌──────────────────┐ │ Check Device │ │ • Device ID │ │ • Fingerprint │ │ • IP / Location │ └────────┬─────────┘ │ ▼ Is Device Known? │ ┌────┴────┐ ▼ ▼ Yes No │ │ ▼ ▼ Home 🎉 Login Method? │ ┌───────┼───────┐ ▼ ▼ ▼ OTP Password OAuth │ │ │ ▼ ▼ ▼ Home 🎉 OTP OTP Required Required │ │ ▼ ▼ Verify Verify │ │ ▼ ▼ Register Device │ ▼ Home 🎉 ``` ### Device Trust Rules | Login Method | New Device Action | Reason | |--------------|-------------------|--------| | OTP | None | OTP = already verified | | Password | Require OTP | Password could be stolen | | OAuth | Require OTP | Token could be compromised | --- ## 6. Risk Scoring | Signal | Low Risk | High Risk | |--------|----------|-----------| | Location | Same country | New country | | Device | Similar OS | Different OS | | IP | Normal | VPN / Proxy | | Account | Active | Dormant | | Time | Normal hours | Unusual hours | ### Action by Risk ``` Risk Score │ ├── Low Risk ──► Soft verify (email link, approve from known device) │ └── High Risk ──► Phone OTP required ``` --- ## 7. UI Screens ### Sign Up Screen ``` ┌─────────────────────────────────────┐ │ │ │ Create Account 🚀 │ │ │ │ ┌───────────────────────────────┐ │ │ │ Phone or Email │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Continue │ │ │ └───────────────────────────────┘ │ │ │ │ ── or ── │ │ │ │ [Google] [Apple] │ │ │ │ Already have account? Login │ │ │ └─────────────────────────────────────┘ ``` ### OTP Verification Screen ``` ┌─────────────────────────────────────┐ │ │ │ Verify OTP 🔐 │ │ │ │ Enter code sent to: │ │ +255 712 345 678 │ │ │ │ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └───┘ └───┘ └───┘ └───┘ └───┘ └───┘ │ │ │ Resend code (0:45) │ │ │ └─────────────────────────────────────┘ ``` ### Age & Name Screen ``` ┌─────────────────────────────────────┐ │ │ │ Let's get started 📅 │ │ │ │ First name: │ │ ┌───────────────────────────────┐ │ │ │ John │ │ │ └───────────────────────────────┘ │ │ │ │ Last name: │ │ ┌───────────────────────────────┐ │ │ │ Doe │ │ │ └───────────────────────────────┘ │ │ │ │ Date of birth: │ │ ┌───────────────────────────────┐ │ │ │ 1999 / 05 / 15 │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Continue │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### Username Screen ``` ┌─────────────────────────────────────┐ │ │ │ Pick Username 🏷️ │ │ │ │ ┌───────────────────────────────┐ │ │ │ @johndoe99 │ │ │ └───────────────────────────────┘ │ │ │ │ ✅ @johndoe99 is available │ │ │ │ Suggestions: │ │ @johndoe_tz @jdoe99 @the_john │ │ │ │ ┌───────────────────────────────┐ │ │ │ Continue │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### Contact Verification Screen (Email/OAuth users only) ``` ┌─────────────────────────────────────┐ │ │ │ Add your phone number 📱 │ │ │ │ Your email j•••@g••••.com ✅ │ │ │ │ Needed for: │ │ • SMS reminders │ │ • Account security and recovery │ │ │ │ ┌───────────────────────────────┐ │ │ │ +255 _____________________ │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Send Code │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### Interests Screen ``` ┌─────────────────────────────────────┐ │ │ │ Pick Your Interests 🎯 │ │ (at least 3) │ │ │ │ ┌─────────┐ ┌─────────┐ ┌───────┐ │ │ │ Fashion │ │ Tech │ │ Music │ │ │ └─────────┘ └─────────┘ └───────┘ │ │ ┌─────────┐ ┌─────────┐ ┌───────┐ │ │ │ Sports │ │ Food │ │Gaming │ │ │ └─────────┘ └─────────┘ └───────┘ │ │ ┌─────────┐ ┌─────────┐ ┌───────┐ │ │ │ Travel │ │ Art │ │Fitness│ │ │ └─────────┘ └─────────┘ └───────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Continue │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### Profile Setup Screen ``` ┌─────────────────────────────────────┐ │ │ │ Complete Profile ✨ │ │ (optional) │ │ │ │ ┌─────────┐ │ │ │ 📷 │ │ │ └─────────┘ │ │ Add photo │ │ │ │ Display name: │ │ ┌───────────────────────────────┐ │ │ │ John Doe │ │ │ └───────────────────────────────┘ │ │ │ │ Bio: │ │ ┌───────────────────────────────┐ │ │ │ Music lover | Dar es Salaam 🇹🇿│ │ │ └───────────────────────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ Complete │ │ Skip for now │ │ │ └──────────────┘ └──────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### Login Screen ``` ┌─────────────────────────────────────┐ │ │ │ Welcome Back 👋 │ │ │ │ ┌───────────────────────────────┐ │ │ │ Phone, email, or username │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ Continue │ │ │ └───────────────────────────────┘ │ │ │ │ ── or ── │ │ │ │ [Google] [Apple] │ │ │ │ Don't have account? Sign up │ │ │ └─────────────────────────────────────┘ ``` ### Login Method Choice (if password exists) ``` ┌─────────────────────────────────────┐ │ │ │ How do you want to login? │ │ │ │ ┌───────────────────────────────┐ │ │ │ 📱 Send me OTP │ │ │ └───────────────────────────────┘ │ │ │ │ ┌───────────────────────────────┐ │ │ │ 🔑 Use password │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### OTP Destination Choice (username login) ``` ┌─────────────────────────────────────┐ │ │ │ Send OTP to: │ │ │ │ ○ ••• ••• ••45 │ │ ○ j••••••@g••••.com │ │ │ │ ┌───────────────────────────────┐ │ │ │ Send OTP │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` ### New Device Detected ``` ┌─────────────────────────────────────┐ │ │ │ 🆕 New device detected │ │ │ │ For your security, verify it's │ │ you with a one-time code. │ │ │ │ ○ ••• ••• ••45 │ │ ○ j••••••@g••••.com │ │ │ │ ┌───────────────────────────────┐ │ │ │ Send OTP │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` --- ## 8. Security Settings (Post-onboarding) ``` ┌─────────────────────────────────────┐ │ │ │ Security Settings 🔒 │ │ │ ├─────────────────────────────────────┤ │ │ │ Phone │ │ ┌───────────────────────────────┐ │ │ │ +255 712 XXX XXX ✅ Verified│ │ │ └───────────────────────────────┘ │ │ │ │ Email │ │ ┌───────────────────────────────┐ │ │ │ Not added [Add now] │ │ ← phone users see this │ └───────────────────────────────┘ │ │ 💡 Add email for ticket delivery │ │ │ │ Password │ │ ┌───────────────────────────────┐ │ │ │ Not set [Add] │ │ │ └───────────────────────────────┘ │ │ 💡 Optional extra security │ │ │ ├─────────────────────────────────────┤ │ │ │ Linked Accounts │ │ ┌───────────────────────────────┐ │ │ │ Google Not linked [Link] │ │ │ │ Apple Not linked [Link] │ │ │ └───────────────────────────────┘ │ │ │ └─────────────────────────────────────┘ ``` --- ## 9. Summary ### Sign Up | Path | Steps | |------|-------| | Phone | OTP → Age → Username → Interests → Profile → Home | | Email | OTP → Age → Username → **Verify Phone** → Interests → Profile → Home | | OAuth | Authorize → Age → Username → **Verify Phone** → Interests → Profile → Home | ### Login | Has Password? | Options | |---------------|---------| | No | OTP only | | Yes | Choose: OTP or Password | ### Device Verification | Login Method | New Device Action | |--------------|-------------------| | OTP | None (OTP = verification) | | Password | OTP required | | OAuth | OTP required | ### Post-Onboarding Nudges (Phone users) | Feature | Requires Email? | Behaviour | |---------|----------------|-----------| | Browse feed | No | Free | | Buy ticket | No | Free | | Receive ticket via email | Yes | Nudge to add email | | Account recovery | Yes | Nudge to add email |