Skip to main content

Onboarding And Authentication Module

Quick Answer​

The onboarding module lives in src/core/onboarding. It contains walkthrough, welcome, login, signup, phone authentication, password reset, delayed login, persistent auth state, and provider-based authentication logic.

Most apps use Firebase Auth by default. Some app packages also include AWS, custom backend, or local provider implementations when that product needs them.

Source Map​

src/core/onboarding
├── api
├── components
├── hooks
├── redux
├── screens
└── utils

Important pieces:

File or folderPurpose
screens/LoadScreenDecides the first visible screen based on auth state and walkthrough state.
screens/WalkthroughScreenIntro carousel or product walkthrough.
screens/WelcomeScreenEntry screen for login/signup actions.
screens/LoginScreenEmail and password login.
screens/SignupScreenEmail and password account creation.
screens/SmsAuthenticationScreenPhone authentication and SMS verification.
screens/ResetPasswordScreenPassword reset flow.
hooks/useCurrentUserReads the signed-in user from app state.
api/index.tsSelects Firebase, AWS, backend, or local auth provider.
redux/auth.tsAuth reducer used by apps that still use Redux state.

Backend Provider​

The active authentication backend is selected in:

src/core/onboarding/api/index.ts

Firebase-backed apps import:

import authManager from './firebase/firebaseAuthManager'

If you replace Firebase with your own backend, implement the same auth manager methods in src/core/onboarding/api/backend and switch the export in api/index.ts.

Common Auth Methods​

The auth manager is expected to support methods such as:

retrievePersistedAuthUser()
loginWithEmailAndPassword(email, password)
createAccountWithEmailAndPassword(userDetails, appConfig)
logout(user)
sendSMSToPhoneNumber(phoneNumber, appConfig)
loginWithSMSCode(verificationID, code, appConfig)

Social auth methods are enabled only in app packages that include the required native dependencies and provider config.

Firebase Auth Setup​

For Firebase apps, configure:

  • Email/password auth if the app exposes email login.
  • Phone auth if the app exposes SMS login.
  • Apple Sign In if iOS social auth is enabled.
  • Google Sign-In if the app exposes Google login.
  • Firestore users collection writes after signup/login.
  • Storage/media upload if signup allows profile photo upload.
  • Push token update if the app sends notifications after login.

Use the Firebase docs section for the project-level setup:

Google Sign-In​

If the app includes Google Sign-In:

  1. Enable Google as a provider in Firebase Authentication.
  2. Configure the native iOS and Android client IDs in Firebase.
  3. Add the web client ID to the app config field used by the app.
  4. Reinstall Pods after native config changes.
  5. Test on a real device and with a Firebase test user.

Do not copy client IDs from another Firebase project. They must match the app's bundle ID, package name, and Firebase project.

Custom Backend​

To use a custom backend:

  1. Implement the auth manager contract in src/core/onboarding/api/backend.
  2. Keep Firebase-only imports out of the active backend path.
  3. Return the user shape expected by useCurrentUser and app screens.
  4. Persist credentials/session tokens through the existing storage helper or your own secure storage layer.
  5. Update profile, push token, and user document flows to call your backend.
  6. Test logout, account deletion, password reset, and expired session behavior.

Verification Checklist​

Test:

  • app starts logged out;
  • walkthrough state persists;
  • email signup;
  • email login;
  • logout;
  • password reset;
  • phone auth if enabled;
  • Apple/Google login if enabled;
  • profile photo upload during signup if enabled;
  • denied or failed auth state returns a clear error;
  • current user is available through useCurrentUser.

Troubleshooting​

ProblemFix
App opens to the wrong screenCheck persisted auth state and walkthrough state in LoadScreen.
Google login failsVerify Firebase provider setup, native client IDs, reversed client ID on iOS, and app config web client ID.
Phone auth failsConfirm Firebase phone auth is enabled and platform-specific SHA/APNs settings are complete.
Signup works but profile photo failsCheck src/core/media, Firebase Storage/Functions, and Blaze plan requirements.
Custom backend logs in but app state is emptyMatch the user object shape expected by reducers, hooks, and profile screens.