Skip to content

[$500] Centralize navigation redirects with guard system #79974

Closed

Description

@mountiny

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 OwnerCurrent Issue Owner: @CortneyOfstad

Activity

  1. added
    BugSomething is broken. Auto assigns a BugZero manager.
    on Jan 20, 2026
  2. melvin-bot commented on Jan 20, 2026

    @melvin-bot

    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.

  3. TMisiukiewicz commented on Jan 23, 2026

    @TMisiukiewicz
    Contributor

    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:

    • Test drive modal
    • Migrated user welcome modal
    • Explanation modal

    Once it's done, the logic responsible for handling redirects in useOnboardingFlow should be removed

  4. mountiny commented on Jan 24, 2026

    @mountiny
    ContributorAuthor

    Amazing thank you

  5. 36 remaining items

  6. eh2077 commented on Mar 19, 2026

    @eh2077
    Contributor

    I think payment is sorted as @TMisiukiewicz is from agency team.

  7. mountiny commented on Mar 19, 2026

    @mountiny
    ContributorAuthor

    I think @TMisiukiewicz still wanted to follow up but maybe we can do that in new issue

  8. TMisiukiewicz commented on Mar 19, 2026

    @TMisiukiewicz
    Contributor

    Yeah we can do the follow up in a new issue if needed, no problem

  9. melvin-bot commented on Mar 20, 2026

    @melvin-bot

    ⚠️ Looks like this issue was linked to a Deploy Blocker here

    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.

  10. CortneyOfstad commented on Mar 23, 2026

    @CortneyOfstad
    Contributor

    Can we confirm if this is tied to a deploy blocker?

  11. eh2077 commented on Mar 23, 2026

    @eh2077
    Contributor

    No, that's a false alarm, see #85895 (comment)

  12. JmillsExpensify commented on Mar 24, 2026

    @JmillsExpensify
    Contributor

    $500 approved for @eh2077

  13. moved this from AWAITING DEPLOYMENT to Done in [#whatsnext] #qualityon Mar 25, 2026
  14. sobitneupane commented on May 25, 2026

    @sobitneupane
    Contributor

    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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Awaiting PaymentAuto-added when associated PR is deployed to productionBugSomething is broken. Auto assigns a BugZero manager.DailyKSv2

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions