Repository navigation
Description
Design Doc
https://docs.google.com/document/d/1rqbBWVJoOtyptW6IcyzodKq-1l8e9qXVYDm2_6Raots/edit?tab=t.0
Proposal
Made by Yehor (@collectioneur) in https://expensify.slack.com/archives/C08CZDJFJ77/p1758798849102299
Background:
Right now, our navigation system relies on special URL parameters called backTo and forwardTo. These parameters are used when a user opens a screen that is reused in multiple different flows (for instance, the VerifyAccountPage is used in both settings/wallet and workspaces/:policyID/invoices.). Their purpose is to make sure that, if the page is refreshed or opened from a link, the app knows where to send the user back to or forward to.
The downside is that these parameters make our URLs long and messy. Because of this, we’re currently running a large refactor to remove them from the URL. The current approach is to replace them by adding separate routes for every flow that uses such a screen, usually one or two routes at a time. By the time this refactor is done, we’ll end up with 240 new routes. With static URLs, adding just one route typically means touching at least seven files (often more) and configuring all required parameters.
Problem:
The issue with this approach is scale. For every flow and every screen that currently depends on backTo or forwardTo, we need to create a dedicated route. On top of that, we often need to configure extra path parameters (like reportId or policyId) so that no information is lost. These routes will clutter navigation files, make them harder to maintain, and add a lot of weight to the code - all for the single purpose of removing backTo and forwardTo.
Solution:
Instead of creating static routes, we can introduce a dynamic URL modification system. This system would update the path directly by appending a short suffix to the URL (different for each component that previously relied on backTo). All other parameters would remain intact.
(Using the same example, it would work like this:
settings/wallet -> settings/wallet/verify-account
workspaces/12345/invoices -> workspaces/12345/invoices/verify-account)
This means we can always reconstruct the “back” path simply by trimming off the suffix, while keeping the URL short, clean, and user-friendly. Most importantly, we would not need to create any additional routes or components at all — they would be handled dynamically.
With static routes, we have to mount the same component separately for each static route. With the dynamic approach, it's mounted only once and then reused.
This approach greatly reduces the amount of code, speeds up the refactor, and keeps navigation files lean.
A working example of this solution is already implemented in this PR for the VerifyAccount screen.
In the thread, I’ve attached a comparison showing what a dynamic URL looks like versus what we have now.
Tasks
- Post Proposal (full Problem/Solution statement) in
#expensify-open-source - Wait at least one full business day, and until the post has a majority (2/3) of positive reactions (👍)
- Paste Proposal in the space above with a link to the Slack thread
- Email
strategy@expensify.comand paste in the Proposal - Fill out the High-level overview of the problem, Timeline, and Terminology sections of the Design Doc
- Email
strategy@expensify.com(continue the same email chain as before) with the link to your Design Doc - Host a pre-design meeting (example) in
#expensify-open-sourceto discuss any necessary details in public before filling out the High-level of proposed solution section. - Fill out the High-level of proposed solution section
- Email
stategy@expensify.comagain with links to the doc and pre-design conversation in Slack - Add the
DesignDocReviewlabel to get the High-level of proposed solution section reviewed - Respond to any questions or concerns and bring up blockers in Slack to get a consensus if necessary
- Confirm that the doc has the minimum necessary number of reviews before proceeding
- Host another pre-design meeting in
#expensify-open-sourceto ask for engineering feedback on the technical solution. - Fill out the Detailed implementation of the solution and related sections.
- Re-add the
DesignDocReviewlabel to this issue - Respond to any questions or concerns and bring up blockers in Slack to get consensus if necessary
- Confirm that the doc has the minimum necessary number of reviews before proceeding
- Email
strategy@expensify.comone last time to let them know the Design Doc is moving into the implementation phase - Implement the changes
- Add regression tests so that QA can test your feature with every deploy (instructions)
- Send out a follow up email to
strategy@expensify.comonce everything has been implemented and do a Project Wrap-Up retrospective that provides:- Summary of what we accomplished with this project
- What went well?
- What could we have done better?
- What did we learn?
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsHIGH
Activity
melvin-bot commentedon Oct 30, 2025
Triggered auto assignment to @jliexpensify (
NewFeature), see https://stackoverflowteams.com/c/expensify/questions/14418#:~:text=BugZero%20process%20steps%20for%20feature%20requests for more details. Please add this Feature request to a GH project, as outlined in the SO. Remember to draft any necessary HelpDot updates by following the instructions here.melvin-bot commentedon Oct 30, 2025
melvin-bot commentedon Oct 30, 2025
Triggered auto assignment to Design team member for new feature review - @dubielzyk-expensify (
NewFeature)mjasikowski commentedon Oct 30, 2025
Unassigning @dubielzyk-expensify, as this is a small technical project that doesn't involve any design.
@jliexpensify feel free if you want to unassign yourself too
82 remaining items
mjasikowski commentedon Jun 24, 2026
Still in implementation
mjasikowski commentedon Jul 27, 2026
Same
mjasikowski commentedon Sep 1, 2026
In progress
mjasikowski commentedon Oct 5, 2026
Done, will send closing email this week