feat: Unified Multi-Step Registration Flow at /auth route

[FirezTheGreat]

Feature Description

📌 Goal

Implement a unified registration and login flow using a shared /register route.

This flow allows users to start with email and the backend will intelligently route them into login or sign-up flows based on whether they already exist in the system.

🧠 Behavior Overview

🆕 New Users (Get Started)

1. User enters email →.
2. If email is not registered:
   • system sends verification code.
   • They continue the registration flow after verifying code.
   • Name and other onboarding details are collected.
   • JWT issued and redirected to onboarding/dashboard.

🔐 Existing Users

1. If a known email is entered on /register:
   • We redirect to login page, before sending OTP by checking our database.
   • Autofill email and ask for password directly.
   • Authenticate and redirect to dashboard.

---

🔁 Smart Redirection Between Login and Register

• If a user enters a registered email under "Get Started", redirect them to the login flow (with email autofilled).
• If a user starts on login page but the email doesn’t exist:
  • Redirect to /register.
  • Autofill email they've already entered and send a verification code.
  • Ask for name and other onboarding details.
  • Continue registration process from there.
  • JWT issued and redirected to onboarding.

---

🔐 Authentication Method

• OTP-based email verification (6-digit code)
• Password-based login for returning users
• Session handled using JWT

---

🗂 UX Summary

All of this happens on:

• /register → Multi-step UI using internal component state
• /login → Basic password auth UI
• Seamless switching between them based on user existence

---

🔧 Backend Routes Needed

Endpoint	Method	Description
/api/auth/verify-email	POST	Send OTP (returns if user exists or not)
/api/auth/verify-otp	POST	Validate OTP and add user details to the database
/api/auth/login	POST	Email/password login

---

🧩 Notes

• Add email existence check before sending OTP
• Add field pre-fill and redirection logic between flows
• Rate-limit OTP requests
• Secure all auth flows using JWT (cookies)

---

📎 Related

Will be implemented in: feature/auth-flow branch

Use Case

This feature enhances the user experience by streamlining the registration and login process into a unified, intelligent flow. Instead of forcing users to choose between "login" and "sign up" upfront, the system makes that decision based on their email.

• Users who have already registered are redirected to login automatically — reducing confusion and redundant signups.
• First-time users are smoothly guided through the necessary steps (verification → details → onboarding) without breaking flow.
• Users who start on the wrong screen (e.g., entering a new email on the login page) are redirected with their input preserved, making the transition effortless.
• It mirrors the smooth, minimal-friction UX of modern tools like Linear, Notion, and Superhuman.
• Keeps the frontend UI simple by consolidating logic while ensuring flexibility for both new and returning users.

This improves user trust, reduces drop-offs, and makes the overall experience feel polished and thoughtful.

Affected Areas

This feature will impact both the authentication logic and related frontend components.

🗂️ Frontend

• /register route: New multi-step form logic
• /login route: Autofill + redirect logic for new users
• Auth-related components:
  • EmailForm.jsx
  • CodeVerification.jsx
  • DetailsForm.jsx
  • LoginForm.jsx
• Shared form state management

🚦 Backend

• Auth controller logic
  • /api/auth/verify-email
  • /api/auth/verify-otp
  • /api/auth/login
• User model/database lookup for email checks
• OTP generation and validation
• JWT issuance and cookie handling

Additional Context