Merge pull request Expensify#67188 from Expensify/tgolen-routing-philosophy

[No QA] Add a page to our docs about our routing philosophy

Author: tgolen

README.md

@@ -24,6 +24,7 @@
 * [canBeMissing onyx param](#canbemissing-onyx-param)
 
 #### Additional Reading
+* [Application Philosophy](contributingGuides/philosophies/INDEX.md)
 * [API Details](contributingGuides/API.md)
 * [Offline First](contributingGuides/OFFLINE_UX.md)
 * [Contributing to Expensify](contributingGuides/CONTRIBUTING.md)
@@ -525,7 +526,7 @@ You can only build HybridApp if you have been granted access to [`Mobile-Expensi
 4. Run `git config --global submodule.recurse true` in order to have the submodule updated when you pull App.
 
 
-> [!Note]  
+> [!Note]
 > #### For external agencies and C+ contributors only
 >
 > If you'd like to modify the `Mobile-Expensify` source code, it is best that you create your own fork. Then, you can swap origin of the remote repository by executing this command:
@@ -560,15 +561,15 @@ If for some reason, you need to target the standalone NewDot application, you ca
 
 ### Working with HybridApp vs Standalone NewDot
 
-Day-to-day work with **HybridApp** shouldn't differ much from working on the standalone **NewDot** repository.  
-The primary difference is that the native code, which runs React Native, is located in the following directories:  
+Day-to-day work with **HybridApp** shouldn't differ much from working on the standalone **NewDot** repository.
+The primary difference is that the native code, which runs React Native, is located in the following directories:
 
 - `./Mobile-Expensify/Android`
 - `./Mobile-Expensify/iOS`
 
 ### Important Notes:
 1. **Root Folders Do Not Affect HybridApp Builds:**
-   - Changes made to the `./android` and `./ios` folders at the root of the repository **won't affect the HybridApp build**.  
+   - Changes made to the `./android` and `./ios` folders at the root of the repository **won't affect the HybridApp build**.
 
 2. **Modifying iOS Code for HybridApp:**
    - If you need to remove `Pods`, you must do it in the **`./Mobile-Expensify/iOS`** directory.
@@ -583,23 +584,23 @@ The primary difference is that the native code, which runs React Native, is loca
 
 ### Updating the `Mobile-Expensify` Submodule
 
-The `Mobile-Expensify` directory is a **Git submodule**. This means it points to a specific commit on the `Mobile-Expensify` repository.  
+The `Mobile-Expensify` directory is a **Git submodule**. This means it points to a specific commit on the `Mobile-Expensify` repository.
 
-If you'd like to fetch the submodule while executing the `git pull` command in `Expensify/App` instead of updating it manually you can run this command in the root of the project: 
+If you'd like to fetch the submodule while executing the `git pull` command in `Expensify/App` instead of updating it manually you can run this command in the root of the project:
 
 ```
 git config submodule.recurse true
 ```
 
-> [!WARNING]  
+> [!WARNING]
 > Please, remember that the submodule will get updated automatically only after executing the `git pull` command - if you switch between branches it is still recommended to execute `git submodule update` to make sure you're working on a compatible submodule version!
 
 If you'd like to download the most recent changes from the `main` branch, please use the following command:
 ```bash
 git submodule update --remote
 ```
 
-It's important to emphasize that a git submodule is just a **regular git repository** after all. It means that you can switch branches, pull the newest changes, and execute all regular git commands within the `Mobile-Expensify` directory. 
+It's important to emphasize that a git submodule is just a **regular git repository** after all. It means that you can switch branches, pull the newest changes, and execute all regular git commands within the `Mobile-Expensify` directory.
 
 ### Adding HybridApp-related patches
 
@@ -805,7 +806,7 @@ Some pointers:
 - When working with translations that involve plural forms, it's important to handle different cases correctly.
 
   For example:
-  - zero: Used when there are no items **(optional)**. 
+  - zero: Used when there are no items **(optional)**.
   - one: Used when there's exactly one item.
   - two: Used when there's two items. **(optional)**
   - few: Used for a small number of items **(optional)**.

contributingGuides/philosophies/INDEX.md

@@ -0,0 +1,5 @@
+# Application Philosophies
+The following pages include details on how different systems are meant to be used.
+
+## Contents
+* [Routing Philosophy](contributingGuides/philosophies/ROUTING.md)

contributingGuides/philosophies/ROUTING.md

@@ -0,0 +1,68 @@
+# Routing Philosophy
+Learn how URLs are constructed and used to route users through all parts of the application.
+
+[React Navigation](https://reactnavigation.org/) is the library used for all routing and navigation, so refer to its [docs](https://reactnavigation.org/docs/getting-started) to understand how the library works. This page will not focus on how routing works, but how URLs are constructed and what patterns to follow when adding new URLs.
+
+## Definitions
+- URL - The web address for every page in the app. On web, this is shown on the browser bar, and is of the format `https://new.expensify.com/<route>`
+- Route - A unique identifier of a specific location within the app's navigation hierarchy
+- Object Route - A route pointing to a specific object (eg. report, transaction, workspace, etc.)
+- Page Route - A route for a specific page (eg. settings, add bank account, etc.)
+
+This guide is based on [[PSR-1]] and [[PSR-2]].
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
+"OPTIONAL" in this document are to be interpreted as described in [[RFC 2119]].
+
+## Rules
+When adding new routes, or refactoring existing routes, follow these rules:
+
+### - MUST be unique
+There are no aliases where different routes lead to the same place.
+
+### - SHOULD be short
+Aim for the shortest possible URL that is also still human readable.
+
+Exceptions:
+- When abbreviated paths are used in specific instances like `r/` (for reports) and `a/` (for accounts) for strategic purposes
+
+### - MUST use kebab-case for all parts of a URL (eg. words separated by hyphens)
+### - MUST use all lower case words
+### - MUST be defined in `ROUTES.ts`
+### - MUST convey page hierarchy
+Just like breadcrumbs, the URL should reflect the path a user has taken.
+
+Example of the paths taken to manage a workspace member:
+1. `workspaces`
+1. `workspaces/:policyID/overview`
+1. `workspaces/:policyID/members`
+1. `workspaces/:policyID/members/:memberID`
+
+### - MUST have the route parameters validated
+Since users can edit the route parameters at any time, to any value, the parameters must always be validated to ensure they are correct and the user has access.
+
+### - MUST NOT start with a slash
+### - MUST NOT contain jargon or acronyms
+### - MUST NOT contain sensitive information that could be logged by third-parties
+Internet routers and third-party-services can see and store any information in the URL. Do not put things like passwords, auth tokens, or PII (personally identifiable information).
+
+### - SHOULD NOT use query parameters
+Exceptions:
+- When a URL needs to be encoded and added to the path (eg. `?backTo=URL`, `?forwardTo=URL`)
+- When complex data needs to be part of the path (eg. `/search?q=QUERY`)
+
+### - SHOULD NOT use optional parameters
+If there are optional parameters, use two separate route definitions instead to be explicit.
+
+### - SHOULD use plural nouns when there are multiple objects that can exist
+Exceptions:
+
+- When abbreviated paths are used in specific instances like `r/` (for reports) and `a/` (for accounts) then plurality does not matter
+
+### - SHOULD use only the minimal necessary information to render the page
+Examples:
+- `r/:threadReportID` GOOD - `threadReportID` is all that is needed and all the rest of the page can be derived from that
+- `r/:parentReportID/:threadReportID` BAD - the `parentReportID` is not necessary so it just adds cruft to the URL
+
+Exceptions:
+
+- When multiple IDs are **required** to render the page.

src/ROUTES.ts

@@ -1,3 +1,8 @@
+/**
+ * NOTE!!!!
+ *
+ * Refer to ./contributingGuides/philosophies/ROUTING.md for information on how to construct routes.
+ */
 import type {TupleToUnion, ValueOf} from 'type-fest';
 import type {SearchQueryString} from './components/Search/types';
 import type CONST from './CONST';