# Upgrade content-server's tech stack by moving remaining routes into fxa-settings

* Status: proposed
* Deciders: Mill Soper, Lauren Zugai, Vijay Budhram, Ben Bangert
* Date: 2022-11-18

Technical Story: [FXA-3915]([FXA-3915](https://mozilla-hub.atlassian.net/browse/FXA-3915)), [FXA-6102]([FXA-6102](https://mozilla-hub.atlassian.net/browse/FXA-6102))

## Context and Problem Statement

Many views in the content-server are still served up and rendered via [Backbone.js](https://backbonejs.org/), an increasingly out-of-date framework. To bring those views up-to-date and to bring down technical debt, we have already [converted the Settings views to React.js](https://jira.mozilla.com/browse/FXA-840) and moved them into [a separate React.js app](https://github.com/mozilla/fxa/blob/main/docs/adr/0011-create-new-react-app-for-settings-redesign.md). Now, we want to follow that example and [convert the remaining content-server routes to React.js](https://mozilla-hub.atlassian.net/browse/FXA-3915).

Open questions include how we'll handle API calls from the new pages, where the new views will live, how we'll safely roll these changes out to users, what any backend work may look like, and how we'll clean up the rollout infrastructure when we're finished.

## Decision Drivers

* We want to make the changes as safe as possible, minimizing any chance of disruption to the user experience
* We want to avoid any unnecessary work and clip out extra steps wherever possible.
* Rolling out changes (and cleaning up upon successful rollout) should be as simple as possible.
* For the sake of both simplicity and efficiency, we should lean on the decisions made in the `fxa-settings` conversion as much as possible.

## Decisions and Considered Options

### Location of Converted Views

- **Option A: New React App**: the new content-server routes could be hosted in a separate React app alongside the `fxa-settings` app. This would allow us to leave the Settings app untouched and unchanged.
- **Option B: Shared React App**: we could convert the existing React.js app (currently only used for `fxa-settings`) to also house the new routes.
- **Option C: Refactor Backbone Views in React**: embed React components in Backbone views, see more details from [a previous ADR here](https://github.com/mozilla/fxa/blob/main/docs/adr/0011-create-new-react-app-for-settings-redesign.md#option-b---take-the-1000-approach-by-creating-all-new-components-with-react-but-modify-existing-backbonemustache-files-or-refactor-these-components-as-react-components).

### Incremental Rollout Approach

#### Context

##### Groups of work
Many routes need to be released in a block or batch, like the routes for the `reset_password` flow, for incremental rollout and to ensure routes that depend on each other, e.g. flows, work as expected. At the time of writing planning is still underway, but there may be as many groups of work as 9, which we can use experiment groups or feature flags we can turn on or off with boolean-valued environment variables to enable.

##### `/beta` URL

In the options below, the `/beta` route refers to an approach we originally took with the new Settings React application where our express framework served Settings at routes that began with `/beta` so "new settings" could be tested at `/beta/settings/*` while "current settings" was still available at `/settings/*`. The alternative is to create a delta at the same path that Express can account for, e.g. `/reset_password` could show the existing content-server route while `/reset_password?showReactApp=true` shows the React version. We don't have access to experiment status at the routing level since our experiment infra spins up at Backbone app start, but we can check for this parameter and if a feature flag is turned on on.

`Pros and cons`: A `/beta` route offers faster development setup but would require a plan of attack to migrate the routes without "beta" at a later time, implement per route, and re-QA, which was not the case for Settings because all routes were under the parent `/settings` route.

##### Handling experiment status
Note that experiment status is only accessible/functional on the Backbone side since we do not have experiment infrastructure set up in Settings. Regardless of which option is chosen, the React version of content-server routes living in `fxa-settings` will be accessible when a parameter is present and (if we choose a feature flag option) if the feature flag is on. While not entirely ideal, this is not a security risk.

In `fxa-content-server`'s [`router` file](https://github.com/mozilla/fxa/blob/main/packages/fxa-content-server/app/scripts/lib/router.js), we can check experiment status and render the Backbone view via `createViewHandler` or if the user in is the experiment, use `navigateAway` to the route with a query parameter.

#### Options

- **Option A: Multiple experiments, no `/beta` route**: Each block of routes will be guarded by separate experiments. If a user is in the experiment, the router will send users to the React version of the page via a paramater.
- **Option B: Multiple experiments, `/beta` route**: Each block of routes will be guarded by separate experiments. If a user is in the experiment, the router will send users to the React version of the page via `/beta/<original_url>` with a parameter. You can see the proposed work for this [here](https://github.com/mozilla/fxa/pull/14436)
- **Option C: A single experiment with config settings, and a `/beta` route**: All routes will be guarded by one experiment and separate feature flags per block of routes. In the router file, we will check experiment status as well as feature flag status before send users to the React version of the page via ``/beta/<original_url>`` with a parameter.
- **Option D: A single experiment with config settings, and no `/beta` route**: All routes will be guarded by one experiment and separate feature flags per block of routes. In the router file, we will check experiment status as well as feature flag status before send users to the React version of the page via a parameter.

#### Other Considerations
`fxa-content-server` does a lot of things on app startup that Settings does not do, like metrics spin up, recognizing relying parties, OAuth and Sync checks, etc. Because we intend on eventually removing `fxa-content-server`, we need Settings to eventually do these things on app startup instead. When this is implemented, we won't need to access query params provided by content-server.

### GQL Usage

#### When to Use
We want to extend the GQL functionality that already exists in `fxa-settings` due to the advantages GQL offers (see decision outcomes) and currently, FxA has only implemented GQL on authenticated pages.

- **Option A: Use GQL only on authenticated routes**: Use GQL on authenticated routes, and continue using REST for API calls when users are unauthenticated
- **Option B: Use GQL everywhere we can**: Add an option per mutation or query to talk to the `graphql-api` without being authenticated, allowing us to use it everywhere **except for likely oauth routes**, which could be another can of worms.

#### Other Implications

If we want to use GQL everywhere we can instead of hitting auth-server directly with REST API calls, and likely even if we're more selective, we have to ensure that the `graphql-api` can handle:

1. Emitting metrics
2. Sending emails
3. Sending push notifications (SQS for event-broker)

- **Option I: Create an API in auth-server that we hit from `graphql-api`**
- Pros: faster to implement
- Cons: because it’s more ideal to move functionality into a shared space instead, we’re kicking the can down the road and will eventually need to remove the newly created API in favor of using the shared services
- **Option II: Move these pieces of functionality into stand-alone library-type services in `fxa-shared` with Typescript**: We can use something like [Bull](https://optimalbits.github.io/bull/) or a job/worker scheme to decouple the service that needs to send an email from the actual email sending service
- Pros: this gets us closer to our preferred architecture in the long-term and mitigates more refactoring work later
- Cons: Large scope increase for this project
- **Option III: Combination of I + II**: Depending on level of effort and scope increase, only port over 1-2 of these features into `fxa-shared`. Create the new temporary API for other features to be refactored later.
- Pros: this could be a happy medium that allows us to continue moving towards our preferred architecture without blocking work
- Cons: Scope increase (less than option B), and still needing refactoring work at a later time (less than option A). May requires us to coordinate plans across teams.

Since Subscription Platform is looking to use GraphQL and move functionality into `graphql-api`, this is also potentially shared work with them.

## Decision Outcomes

### Location of Converted Views

Chosen option: **Option B: Shared React App**, because:
- This is the conventional React approach. A React app can cleanly handle internal routing, and locating all of the views within a single React app is the least confusing pattern for an engineer with work with.
- Shared state (for flow parameters for example) is much easier to handle if we aren't navigating between different apps
- We can more easily shared components between pages
- Navigation between pages will be more efficient

`Positive consequences:` Navigation is faster, the mental model for engineers is simpler (bringing down maintenance complexity), and we don't increase the amount of work to share state across apps.
`Negative consequences:` We do have to put in the work to update (and safely rollout changes to) the Settings app.

### Incremental Rollout Approach

❌
**Chosen option is work-in-progress:** we want to go with option D, a single experiment with config settings, and no `/beta` route, but we are actively planning what the first sprint is going to look like, and we may need the `/beta` approach temporarily. If there is a lot of other work that can be done without this step, like setting up GQL resolvers, we'd prefer to work on the non-beta approach in the next sprint, rather than temporarily going with the `/beta` approach for a couple of routes to then remove it shortly after.
❌

### GQL Usage

❌
**Chosen options are work-in-progress:** We want to go with option A but there are still ongoing discussions around approaches I-III.
❌

Chosen option: **Option A: Extend the GQL functionality that already exists in `fxa-settings`**, because:
- Using GQL for as many routes as possible ensures type consistency with complex type sharing, reduces interactions between backend and frontend, allows the frontend to ask for exactly what it needs, and is consistent with the rest of `fxa-settings`
- Moving towards a more streamlined way of reading and writing data feeds into larger overarching goals

`Positive consequences:` This is consistent with the rest of our modernized stack and we gain all the benefits GQL offers us.
`Negative consequences:` We add on additional work to add the necessary queries/mutations.

### Links
[Proposed `/beta` url PR](https://github.com/mozilla/fxa/pull/14436)
Proposed PR without `/beta` url: Still in progress, will be linked on completion.
[Overarching epic](https://mozilla-hub.atlassian.net/browse/FXA-3915)