Merge pull request #228 from DTS-STN/develop

Release 2022-03-17

.github/README.md

@@ -1,70 +1,94 @@
-## Description
+# Canadian Old Age Benefits Estimator
 
-Quick starter template for DTS projects making use of one of our commonly-used [Next.js](https://nextjs.org/) setups.
-This template uses the basic Next.js [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app) bootstrap template.
+## Overview
 
-### Technologies Implemented
+The Canadian Old Age Benefits Estimator (COABE) is a static web app that will take a client's answers to around six questions and determine if they are eligible for any of the four covered benefits:
 
-This project uses
+- [Old Age Security](https://www.canada.ca/en/services/benefits/publicpensions/cpp/old-age-security.html)
+- [Guaranteed Income Supplement](https://www.canada.ca/en/services/benefits/publicpensions/cpp/old-age-security/guaranteed-income-supplement.html)
+- [Allowance](https://www.canada.ca/en/services/benefits/publicpensions/cpp/old-age-security/guaranteed-income-supplement/allowance.html)
+- [Allowance for the Survivor](https://www.canada.ca/en/services/benefits/publicpensions/cpp/old-age-security/guaranteed-income-supplement/allowance-survivor.html)
 
-- [Next.js](https://nextjs.org/)
-- [Tailwind CSS](https://tailwindcss.com/)
-- [Jest](https://jestjs.io/) for unit testing
-- [Cypress](https://www.cypress.io/) for end-to-end testing.
+If the client is eligible, the tool will also determine the monthly amounts they are entitled to. This logic has been determined using [publicly available data](https://www.canada.ca/en/services/benefits/publicpensions/cpp/payment-amounts.html), in conjunction with internal discussions with policy experts to verify our logic for edge cases.
 
-## How to Implement/Get Started
+The intent is that all values provided by the tool are completely accurate. However, certain edge cases are deliberately not handled due to complexity, which results in no estimation results available. As far as we are aware, all provided estimates are fully accurate, however as the government changes limits and policies, COABE's estimates may become inaccurate. Therefore, we emphasize that any data returned by this tool is not final and is subject to inaccuracy.
 
-### Values that need to be configured:
+## Development: Getting Started
 
-#### Replace eligibility-estimator-client name to new project name
+First, run the development server:
 
-Search "eligibility-estimator-client", replace in package.json, run "npm i" in terminal and confirm package-lock.json is updated
+```bash
+yarn dev
+```
 
-#### Configuring Helm
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
-In the helm template, the application name is single-tier-application. this will need to be changed by the current application name.
+You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
 
-For every Kubernetes cluster, a context.sh file needs to be defined. For example, one might be called context-dev.sh and the other context-prod.sh.
+## Application Architecture
 
-For more information, please visit the [DTS SRE deployment templates](https://github.com/DTS-STN/dts-sre-deployment-templates/tree/main/kubernetes-helm-template).
+COABE was initially built with a traditional frontend plus API approach, where the frontend would have as little logic as possible, and offload the processing whenever possible to the backend API. This separation helped easily distinguish the design and layout (frontend) from the benefit processing logic (backend).
 
-## Deployments
+Since the benefit processing logic was captured as a complex decision tree, and the API's goal was to capture all benefit logic, the frontend needed to constantly re-render its displayed form fields without any previous knowledge of the form. We wanted to avoid having benefit logic in the frontend for ease of maintenance.
 
-Write something about how deployments are done
+The way we accomplished this was to build a "component factory" responsible for receiving a payload containing all data necessary to build the form, such as the questions, the ordering, the question options, and so on. Whenever the client enters data into the form, a request is sent to the backend, and a complete payload is returned to the frontend for re-rendering based on the new input. This proved to work very well, and was highly responsive despite the frequent network requests.
 
-## PR Procedures/Definition of done
+Ultimately, due to issues with certain intricacies of Next.js Static Site Generation, we changed our approach. Instead of sending an API request, the frontend now calls the API code directly (locally). This still uses the exact same logic, and still separates the code for ease of maintenance, however now there are no network requests made at all. This increased responsiveness even further, and simplified deployment, as now there is only a static site to deploy, and no backend API is necessary.
 
-We need to have at least one person reviewing each PR before it can be merged. Also, each branch should be prefixed by the relevant Jira issue, if possible e.g. **DC-13**-comprehensive-readme
+However, while we removed the frontend's usage of the API, it is still fully functional. You may interact with the API directly via `/api/calculateEligibility`, or you may use a "Swagger UI" to interact with it through `/interact`. A live version of this is available [here](https://canadian-old-age-benefits-estimator.vercel.app/interact).
 
-## Useful Links
+### Technologies Used
 
-[TeamCity Link](https://teamcity.dts-stn.com/)
+- [Next.js](https://nextjs.org/): Core framework
+  - The [Next.js documentation](https://nextjs.org/docs) is extremely valuable in understanding how things work, and is a highly recommended read.
+  - See also [Learn Next.js](https://nextjs.org/learn), an interactive Next.js tutorial.
+- [TypeScript](https://www.typescriptlang.org/)
+- [React](https://reactjs.org/): UI framework
+- [React testing library](https://testing-library.com/docs/react-testing-library/intro/): React component testing
+- [Mobx state tree](https://mobx-state-tree.js.org/intro/welcome): React state management
+- [Tailwind CSS](https://tailwindcss.com/)
+- [Jest](https://jestjs.io/): Unit testing
+- [Yarn](https://yarnpkg.com/): Package manager (note this is Yarn v2, and not the classic v1)
 
---- Default Create Next App text: remove or keep or re-use at your discretion ---
+### Frontend
 
-## Getting Started
+#### Additional Details
 
-First, run the development server:
+The payload would then have a key called field data that could be parsed into an array of fields that the component factory would know how to render.
 
-```bash
-npm run dev
-# or
-yarn dev
-```
+A user enters an answer into the form a payload is sent to the back end, processed, and a new payload is sent back defining the current state of the form.
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+The component factory currently supports select components, number field components, currency components, radio button components, and a text field component.
+
+Top of a set of fields there is also the concept of child form fields. This is essentially when a form field is tied to the logic of another form field and renders based on a selection that can occur. For example, there are questions that require partner information and only render when the user is in a common law or marriage relationship.
+
+#### Technology
+
+Because of React's form issues, `mobx-state-tree` and `mobx-react` were used to only re-render when necessary and to control the current state of user inputted data what component's are currently rendered on screen.
+
+You may come across `observer` components, which will observe to the mobx data in the form and only re-render a component if it needs to instead of React's default re-rendering scheme where the parent and all children are automatically re-rendered.
+
+#### File Structure
+
+Below you'll find the file structure as it pertains to the front end.
+
+- `/pages` - Next.js pages, including the API. The structure here determines routing.
+- `/client-state` - state management lives here, all mobx tree node files
+- `/components` - where all the react components live
+- `/public` - any asset or file that needs to be accessible by the application must go here
+- `/styles`
+- `/__tests__`
 
-You can start editing the page by modifying `pages/index.js`. The page auto-updates as you edit the file.
+### Backend
 
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.js`.
+#### Interacting with the API
 
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+Despite the frontend calling the backend code directly and not through an API, the API still exists and is fully functional. You may interact with the API directly via `/api/calculateEligibility`, or you may use a "Swagger UI" to interact with it through `/interact`. A live version of this is available [here](https://canadian-old-age-benefits-estimator.vercel.app/interact). You may also use [Insomnia](https://insomnia.rest/), an open source API client, to interact with the API. If you are using Insomnia, you should import `public/insomnia.yaml` to get set up quickly.
 
-## Learn More
+#### Scraping government data
 
-To learn more about Next.js, take a look at the following resources:
+COABE depends on several pieces of occasionally-changing data from [Canada.ca](https://canada.ca). Rather than requiring developers to copy-paste whenever it changes (it changes quarterly), there is a "scraper" built to automate this process. Simply use `yarn run run-scraper` to pull all necessary "legal values" from the available government sources.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Note that this is prone to breaking, for example if the scraped website changes its layout. In this case you would have to update the "selector" under `/utils/api/scrapers` to match the new layout, and run the script again.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+Unfortunately this scraping should not be fully automated due to the possibility of errors as mentioned above. Any updates require manual review to ensure the scraper is working as intended. That being said, manual review is pretty straightforward, if the numbers are way different or don't exist, there is a problem. Otherwise, it should work as expected.