Repository navigation
Description
Coming from this proposal
Background
When users sign up for Expensify or migrate from OldDot to NewDot, they go through an onboarding flow that consists of several screens (personal details, purpose selection, company size, etc.). The app needs to ensure users complete onboarding before accessing the main application. Currently, this redirect logic exists in multiple places across the codebase: useOnboardingFlow hook (with ~20 dependencies in its useEffect), openReportFromDeepLink action (triggered from Expensify.tsx with minimal dependencies), and various other places that check onboarding status.
Each location independently determines whether to redirect to onboarding and when to do so. The redirect from openReportFromDeepLink typically happens early since it only depends on session data being loaded, while the redirect from useOnboardingFlow happens later due to its many dependencies. Additionally, certain paths like onboarding/migrated-user-welcome are excluded from being saved as the last visited onboarding path, meaning users can be redirected back to different onboarding paths when they reopen the app.
Problem
When navigation redirects are scattered across multiple locations with different dependency arrays, if different redirect logic executes at different times, then users experience race conditions that cause onboarding loops and incorrect navigation states.
Solution
Implement a navigation guard system that centralizes all redirect logic at the router level, eliminating race conditions by evaluating navigation synchronously before any state changes occur.
The guard system eliminates race conditions by moving all redirect decisions to a single evaluation point at the router level. A guard infrastructure with a registry evaluates guards in explicit order, integrated directly into RootStackRouter.getStateForAction() before any routing logic runs. When any navigation action occurs, guards evaluate synchronously with complete, up-to-date Onyx data and can return ALLOW, BLOCK, or REDIRECT results. The OnboardingGuard subscribes to relevant Onyx keys and implements logic to redirect users to onboarding screens when needed, or block navigation away from incomplete onboarding. The scattered redirect logic is removed from useOnboardingFlow, openReportFromDeepLink, and Expensify.tsx, replaced with simple navigation calls that trigger guard evaluation.
Issue Owner
Current Issue Owner: @CortneyOfstadMetadata
Metadata
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
melvin-bot commentedon Jan 20, 2026
Triggered auto assignment to @CortneyOfstad (
Bug), see https://stackoverflow.com/c/expensify/questions/14418 for more details. Please add this bug to a GH project, as outlined in the SO.TMisiukiewicz commentedon Jan 23, 2026
Opened PR for a review with the initial guard system setup and Onboarding guard. Once merged, we should also migrate the following redirects to the guard system:
Once it's done, the logic responsible for handling redirects in
useOnboardingFlowshould be removedmountiny commentedon Jan 24, 2026
Amazing thank you
36 remaining items
eh2077 commentedon Mar 19, 2026
I think payment is sorted as @TMisiukiewicz is from agency team.
mountiny commentedon Mar 19, 2026
I think @TMisiukiewicz still wanted to follow up but maybe we can do that in new issue
TMisiukiewicz commentedon Mar 19, 2026
Yeah we can do the follow up in a new issue if needed, no problem
melvin-bot commentedon Mar 20, 2026
If you are the assigned CME please investigate whether the linked PR caused a regression and leave a comment with the results.
If a regression has occurred and you are the assigned CM follow the instructions here.
If this regression could have been avoided please consider also proposing a recommendation to the PR checklist so that we can avoid it in the future.
CortneyOfstad commentedon Mar 23, 2026
Can we confirm if this is tied to a deploy blocker?
eh2077 commentedon Mar 23, 2026
No, that's a false alarm, see #85895 (comment)
JmillsExpensify commentedon Mar 24, 2026
$500 approved for @eh2077
sobitneupane commentedon May 25, 2026
The PR associated with this issue introduced the following issue:
The problem occurs because the PR adds an onboarding guard, which unintentionally blocks the deeplink navigation during login