Skip to content

feat(auth, users): update login flow, add phone-based account lookup, and implement OTP-based forgot password

Mohana Sri Bhavitha requested to merge login-book_no/bhavitha into develop

Overview

This MR updates the authentication flow in the frontend to align with backend changes. It introduces a book_no-based login, adds a phone number-based account lookup option, and implements a two-step OTP-based forgot password flow.

What does this MR do and why?

Previously:

  • Login supported phone number + password, which caused ambiguity when multiple users shared the same phone number.
  • Forgot password flow was complex and inconsistent.
  • No clear way for users to identify their account if they didn’t know their book number.

Now:

  • Login is strictly based on book_no + password for clarity and security.
  • A new phone-based lookup helps users identify their accounts before login.
  • Forgot password is simplified into a clean OTP-based two-step flow.

This improves:

  • User experience (clear flow)
  • Security (no ambiguous login paths)
  • Consistency with backend logic

Changes Made

1. Login Flow Update

  • Updated login to use:
    • book_no + password (default flow)
  • Removed phone number-based login from default behavior
  • Improved error handling:
    • Displays backend message:
      • "To login create password using forgot password" for first-time users
      • "Invalid credentials" for incorrect login

2. Phone Number-Based Account Lookup (Optional)

  • Added option:
    "Don't know your Book Number? Find using phone number"
  • Calls:
    • GET /api/v1/users/by-phone?phone_no=...
  • Displays:
    • book_no
    • name
    • age
    • roles (supports multiple roles)
  • Fixed UI issue where users were previously shown as "Unknown User"

3. Forgot Password Flow (Updated)

Step 1: Send OTP
  • User enters book_no
  • Calls:
    • POST /api/v1/auth/send-otp
    • { action: "forgot_password", book_no }
  • Handles:
    • User not found → error message
    • Success → shows masked phone number + navigates to reset page
Step 2: Reset Password
  • Inputs:
    • book_no
    • otp
    • new_password
    • confirm_password
  • Calls:
    • POST /api/v1/auth/forgot-password
  • On success:
    • Password updated
    • Redirects to login page

4. OTP Flow Improvements (Frontend Alignment)

  • Integrated new backend validation:
    • OTP only sent for valid users
  • Displays proper error messages:
    • "User not found"
    • "Provide book_no to send otp"
  • Shows masked phone number in success response

Technical Details

  • Updated login API integration:
    • Uses book_no + password
  • Added new API integration:
    • GET /api/v1/users/by-phone
  • Implemented OTP flow:
    • POST /api/v1/auth/send-otp
    • POST /api/v1/auth/forgot-password
  • Implemented state handling for:
    • phone lookup
    • selected account
    • OTP flow navigation
  • Updated error handling to display backend messages dynamically
  • Modified UI to:
    • support optional account lookup
    • handle multi-role users (roles array)
  • Removed deprecated phone-based login logic

Type of Change

  • 🐛 Bug fix (non-breaking change that fixes an issue)
  • ✨ New feature (non-breaking change that adds functionality)
  • 💥 Breaking change (fix or feature that would cause existing functionality to change)
  • 📝 Documentation update
  • 🎨 UI/UX improvement
  • ♻️ Refactor (no functional changes)
  • ⚡ Performance improvement
  • 🧪 Test update
  • 🔧 Configuration change
  • 🚨 Security fix

Related Issues / References

Screenshots or Screen Recordings

Before After
image.png image.png
image.png d153d9a8-65a1-4770-9f43-0ed3315bf3d2.png
image.png image.png

How to Set Up and Validate Locally

  1. Start backend server:
    docker compose up --build
  2. Start frontend:
    npm install
    npm run dev
  3. Open application:
    http://localhost:5173
  4. Validate flows:
  • Login:
    • Enter book_no + password
    • Verify successful login
  • Account Lookup:
    • Click "Find account using phone number"
    • Enter phone number
    • Verify list of users appears
  • Forgot Password:
    • Enter book_no → Send OTP
    • Enter OTP + new password
    • Verify password reset and redirect to login

Testing Done

  1. Start backend server:
    docker compose up --build
  2. Start frontend:
    npm install
    npm run dev
  3. Open application:
    http://localhost:5173
  4. Validate flows:
  • Login:
    • Enter book_no + password
    • Verify successful login
  • Account Lookup:
    • Click "Find account using phone number"
    • Enter phone number
    • Verify list of users appears
  • Forgot Password:
    • Enter book_no → Send OTP
    • Enter OTP + new password
    • Verify password reset and redirect to login

Test Cases Covered:

Scenario Expected Result Status
Login with valid book_no and password User is authenticated, token is stored, and user is redirected to dashboard/home page ✅
Account lookup using phone number Matching user/account list is displayed for the entered phone number ✅
Forgot password flow (book_no → OTP → new password) Password reset succeeds, user is redirected to login, and login works with the new password ✅

Code Quality Checklist

Code Standards

  • Code follows project conventions (naming, structure, formatting)

  • No console.log() or debugger statements left in code

  • No unused imports, variables, or functions

  • No duplicate code and use of existing components for reusability

  • i18n check passed with no hardcoded strings in codebase for i18n support

  • TypeScript types are properly defined (no any unless justified)

  • ESLint and Prettier checks pass

    bun run lint

React Best Practices

  • Components are properly split and single-responsibility
  • Hooks follow rules (no conditional hooks, proper dependencies)
  • State management is appropriate (local vs global state)
  • No unnecessary re-renders (memoization used where needed)
  • Event handlers are properly cleaned up

Component Patterns

  • shadcn/ui components used correctly
  • Tailwind classes follow utility-first approach
  • Responsive design considered (mobile-first if applicable)
  • Accessibility attributes included (aria-*, role, etc.)
  • Icons from lucide-react used consistently

API & Data Fetching

  • TanStack Query used for server state (if applicable)
  • Loading and error states handled
  • API types defined in src/types/api.ts
  • Axios interceptors handle auth tokens correctly
  • Use of Zod for data validations

Error Handling

  • Errors are caught and handled gracefully
  • User-friendly error messages displayed
  • Errors are being toasted properly
  • Network failures handled appropriately

Documentation

  • README.md updated (if setup steps changed)
  • .env.example updated (if new env vars added)
  • CHANGELOG.md updated (if applicable)

Known Limitations / Technical Debt

  • No major new technical debt introduced by this MR.
  • Account lookup and forgot-password flows depend on backend API response shape and availability.
  • Some error states still show generic messages (for example: timeout/invalid OTP variations).
  • Additional negative test coverage is pending (invalid OTP, expired OTP, repeated submit, API timeout).

Additional Notes

  • This MR mainly improves/simplifies auth and user lookup flows.
  • Existing auth architecture is unchanged (AuthContext + token in localStorage) to avoid broader regression risk.
  • No frontend environment variable changes required.
  • CHANGELOG.md updated; README.md and .env.example not updated (no setup/env changes).
  • Manually validated: login, account lookup by phone, forgot-password reset and redirect to login.

MR Acceptance Checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Mohana Sri Bhavitha

Merge request reports