Authentication & Registration

Routes

Route	Purpose	Auth Required
/sign-in	User login	No (redirects to / if authenticated)
/sign-up	New account creation	No (redirects to / if authenticated)
/forgot-password	Password reset request	No
/waiting-for-approve	Registration gate (private beta)	Yes

---

Sign-Up Flow

Methods

1. Email/Password - Form-based registration
2. Google OAuth - One-click via signInWithGoogle()

Fields Collected (Email Registration)

Field	Type	Required	Validation
firstName	text	Yes	Min 1 character
lastName	text	Yes	Min 1 character
email	email	Yes	Valid email format
password	password	Yes	Min 8 characters
agreeToTerms	checkbox	Yes	Must be true

Terms & Conditions

• URL: https://app.termly.io/policy-viewer/policy.html?policyUUID=0e8bd91c-0128-4955-8f7e-e17b7f697a2a
• Opens in new tab
• Must be accepted to register

Post-Signup Actions

1. Firebase Auth account created
2. Display name set as ${firstName} ${lastName}
3. User document created at users/{uid}
4. Referral signup processed (from cookie, silent failure)
5. Analytics events fired
6. Redirect to /
7. Toast: “Account created successfully”

Google Sign-In New User Detection

New user = (Date.now() - creationTime) < 5000ms

If new user detected via Google, referral tracking and sign_up event also fire.

Analytics Events Tracked

Event	When	Key Data
sign_up	Successful registration	method, user_id, email_domain, display_name
sign_up_failed	Registration error	method, error_type
form_interaction	Field focus/blur/change	form_name, field_name, interaction_type
User properties set	On signup	user_type=new, signup_method, account_created_date

---

Sign-In Flow

Fields

Field	Type	Required	Validation
email	email	Yes	Valid email format
password	password	Yes	Min 8 characters

Behavior

• Success: Toast “Signed in successfully”, redirect to /
• Failure: Toast with Firebase error message
• Forgot password link: Navigates to /forgot-password

Analytics Events

Event	Key Data
sign_in_attempt	method, page_location
sign_in	method, user_id, is_new_user, email_domain
sign_in_failed	method, error_type, error_message

---

Password Reset Flow

Steps

1. User navigates to /forgot-password
2. Enters email address (required, valid format)
3. Clicks “Send Email”
4. Firebase Auth sends password reset email
5. Toast: “Password reset email sent”
6. Redirect to /sign-in

The actual password reset is handled by Firebase Auth’s native flow (not within the app).

---

Registration Approval Gate

Route: /waiting-for-approve

What the User Sees

First 5 seconds: Loading animation with “Checking Account Status”

After loading:

• “We’re in Private Beta” headline with badge
• Two options:
  1. Have a Referral Code - Input field + “Link” button
  2. Join the Waitlist - Informational message

Referral Code Linking Flow

1. User enters referral code (or code auto-detected from cookie)
2. System validates code exists at referralCodes/{code} in Firestore
3. If invalid: toast error “Invalid referral code”
4. If valid:
   • Checks for duplicate at referrals/{code}_{userId}
   • Creates referral document at referrals/{code}_{userId}
   • Checks user registry limits at config/userRegistry
5. Auto-approval logic:

   if (registry.enabled && registry.countCurrent < registry.limitUsers) {
     approve user, increment countCurrent
   } else {
     deny approval
   }

User Document Updated on Approval

Field	Value
registrationApproved	true
waitingForApproval	false
isReferred	true
referralId	referral document ID
referralCode	code used
updatedAt	Timestamp.now()

Referral Document Created

Path: referrals/{code}_{userId}

Field	Value
referralCode	code entered
referrerId	code owner’s UID
refereeId	current user’s UID
status	converted
conversionEvent	signup
metadata.signUpSource	waiting-for-approve
metadata.signUpMethod	referral

After Approval

• Toast: “Referral code linked successfully! Redirecting…”
• 2-second delay, then redirect to /

---

Authentication Guards

Guard Chain (App Layout)

AuthGuard (requireAuth=true)
  ├── if route === "waiting-for-approve" → render directly
  └── else:
      ├── CustomGuard #1: checkRegistrationApproved()
      │   ├── FALSE → redirect to /waiting-for-approve
      │   └── TRUE → continue
      └── CustomGuard #2: checkOnboardingCompleted()
          ├── FALSE → redirect to /onboarding
          └── TRUE → render app

Guard Conditions

• checkRegistrationApproved() checks users/{uid}.registrationApproved === true
• checkOnboardingCompleted() checks users/{uid}.onboardingCompleted === true
• Both use server-side reads (getFromServer()) for latest data

---

Cookie & Referral Tracking

On app load, cookieManager.initializeReferralTracking() runs:

1. Extracts referralCode from URL query params
2. Extracts UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
3. Saves to cookies with 90-day expiration (path /, SameSite Lax)
4. Cleans tracking params from browser URL

Cookies Set

Cookie	Content	Expiration
referralCode	Referral code string	90 days
referralData	JSON: {code, timestamp, source, utmParams}	90 days

---

Data Written to Firestore

On Sign-Up

• users/{uid} - User document with email, displayName, email metadata

On Approval

• users/{uid} - Updated with registrationApproved, referral fields
• referrals/{code}_{uid} - Referral transaction record
• config/userRegistry - countCurrent incremented

On Sign-In

• Analytics properties and events only (no Firestore writes)