Candidate Signup and Email Verification Flow#

This document describes the end-to-end flow for candidate signup and email verification in the studenthub-candidate frontend app. It covers the main Angular/Ionic pages, API calls, error handling, UI feedback, and environment configuration.

Signup Screens#

Register Page#

File: src/app/pages/start-pages/register/register.page.ts

The RegisterPage presents a signup form with fields for name, email, phone, password, and language. The form requires a full name (at least two words) and validates all fields. On submission, it executes a Google reCAPTCHA v3 check and then calls AuthService.createAccount(params) to perform the signup API call. If the signup is successful, the backend returns an unVerifiedToken, which is stored locally. The user is then navigated to the verify-email page with their email as a parameter. If the signup fails with error code 2 and candidate_email in the message, the user is redirected to the login page; otherwise, an alert is shown with the backend error message.
Source

Verify Email Page#

File: src/app/pages/start-pages/verify-email/verify-email.page.ts

The VerifyEmailPage retrieves the email (and optional code) from the route parameters. If a code is present, it immediately calls verify(). The page maintains a 60-second cooldown timer for resending verification emails and polls AuthService.isAlreadyVerified every 5 seconds using the stored unVerifiedToken. The user can update their email address (calls AuthService.updateEmail or AccountService.updateEmail depending on login state) and resend the verification email (calls AuthService.resendVerificationEmail with email and reCAPTCHA token).
Source

User Progression#

1. The user opens the RegisterPage and fills out the signup form.
2. On submit, the app validates the form, checks the full name, and runs a reCAPTCHA check.
3. The app calls the signup API. If successful, it stores the unVerifiedToken and navigates to the VerifyEmailPage.
4. The VerifyEmailPage displays the email address and prompts the user to check their inbox for a verification code.
5. The user can enter the verification code (if deep-linked, the code is auto-submitted), resend the code (after the cooldown), or change their email address.
6. The page polls the backend to detect if the email is verified on another device.
7. On successful verification, the app clears timers and tokens and navigates the user to the home or profile completion page.

API Calls#

All API calls are made via AuthService in src/app/providers/auth.service.ts. The following table summarizes the relevant methods:

All endpoints are relative to the base URL configured in the environment files. The Language header is set to the user's current language preference.
Source

Error Handling & UI Feedback#

Registration errors (e.g., validation failures or duplicate email) are surfaced in the RegisterPage via an alert dialog using AuthService.errorMessage(res.message), so users see detailed backend messaging. If the backend returns code 2 with candidate_email, the page routes to the password/login view instead.

Verification errors do not show a blocking alert; instead, verify() sets errorMsg to the backend message and keeps the page in a state where the user can re-enter the code. The loader is hidden. The HTML template displays errorMsg near the code input so the user sees the backend message and can try again.

Resend verification email always shows an alert with the backend message, whether it’s success or a friendly error. If the backend reports that the email is already verified (errorCode == 1) or the account no longer exists (errorCode == 3), the page navigates the candidate back to the landing page to avoid a dead-end.

Timers & polling: After registration, a runTimer flag ensures the resend button is gated for 60 seconds. Additionally, setInterval polls AuthService.isAlreadyVerified every 5 seconds using the stored unVerifiedToken. If the backend reports the email is now verified, the app resolves the signup flow automatically without user action.
RegisterPage source
VerifyEmailPage source

Environment & Base URL#

The API base URL is configured in the environment files:

• Development: src/environments/environment.ts
apiEndpoint: 'https://student.api.dev.studenthub.co/v1'
• Production: src/environments/environment.prod.ts
apiEndpoint: 'https://student.api.studenthub.co/v1'

The Angular build system replaces environment.ts with the appropriate file for the build target. All AuthService requests concatenate this base with endpoint paths such as /auth/register, /auth/verify-email, /auth/resend-verification-email, etc.
Production environment source

Example Signup Flow Diagram#