Skip to content

Commit

Permalink
Added documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
ELiuHub committed Sep 22, 2022
1 parent 1d8ebcb commit f1a8c81
Show file tree
Hide file tree
Showing 26 changed files with 299 additions and 72 deletions.
153 changes: 83 additions & 70 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,70 +1,83 @@
# Getting Started with Create React App

This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).

## Available Scripts

In the project directory, you can run:

### `npm start`

Runs the app in the development mode.\
Open [http://localhost:3000](http://localhost:3000) to view it in your browser.

The page will reload when you make changes.\
You may also see any lint errors in the console.

### `npm test`

Launches the test runner in the interactive watch mode.\
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.

### `npm run build`

Builds the app for production to the `build` folder.\
It correctly bundles React in production mode and optimizes the build for the best performance.

The build is minified and the filenames include the hashes.\
Your app is ready to be deployed!

See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.

### `npm run eject`

**Note: this is a one-way operation. Once you `eject`, you can't go back!**

If you aren't satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.

Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you're on your own.

You don't have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn't feel obligated to use this feature. However we understand that this tool wouldn't be useful if you couldn't customize it when you are ready for it.

## Learn More

You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).

To learn React, check out the [React documentation](https://reactjs.org/).

### Code Splitting

This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)

### Analyzing the Bundle Size

This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)

### Making a Progressive Web App

This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)

### Advanced Configuration

This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)

### Deployment

This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)

### `npm run build` fails to minify

This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)
# Basics for Health

| Index | Description |
| :-------------------------------------------------- | :------------------------------------------------------ |
| [High Level Architecture](#high-level-architecture) | High level overview illustrating component interactions |
| [Deployment](#deployment-guide) | How to deploy the project |
| [User Guide](#user-guide) | The working solution |
| [Files/Directories](#files-and-directories) | Important files/directories in the project |
| [Changelog](#changelog) | Any changes post publish |
| [Credits](#credits) | Meet the team behind the solution |
| [License](#license) | License details |

# High Level Architecture

The following architecture diagram illustrates the various AWS components utliized to deliver the solution. For an in-depth explanation of the frontend and backend stacks, refer to the [Architecture Deep Dive](docs/ArchitectureDeepDive.md).

![Alt text](./docs/images/architecture-diagram.png?)

# Deployment Guide

To deploy this solution, please follow the steps laid out in the [Deployment Guide](docs/DeploymentGuide.md).

# User Guide

For instructions on how to navigate the web app interface, refer to the [Web App User Guide](docs/UserGuide.md).

# Files And Directories

```text
.
├── amplify
├── docs/
│ ├── images/
│ ├── ArchitectureDeepDive.md
│ ├── DeploymentGuide.md
│ └── UserGuide.md
├── node_modules
├── public
├── src/
│ ├── components/
│ │ ├── navbar.js
│ │ └── sidebar.js
│ ├── graphql/
│ ├── pages/
│ │ ├── admin.js
│ │ ├── form.js
│ │ └── upload.js
│ ├── adminStatus.js
│ ├── App.css
│ ├── App.js
│ ├── aws-exports.js
│ ├── index.css
│ ├── index.js
│ ├── reportWebVitals.js
│ └── setupTests.js
├── .gitignore
├── .graphqlconfig.yml
├── .amplify.yml
├── package-lock.json
├── package.json
└── README.md
```

1. **`/docs`**: Contains all relevant documentation files
2. **`/public`**: Contains library for rendering the forms
3. **`/src`**: Contains all the source code for the website
1. **`/components`**: Reusable React components
- navbar.js: App bar for the application
- sidebar.js: Menu to help users navigate between pages
2. **`/graphql`**: Contains files for mutations, queries and the schema
3. **`/pages`**: Files for each individual page of the app
4. **`/adminStatus.js`**: File for checking if the user is an admin

# Changelog
N/A

# Credits

This application was architected and developed by Eric Liu with guidance from the UBC CIC technical and project management teams.

# License

This project is distributed under the [MIT License](https://github.com/git/git-scm.com/blob/main/MIT-LICENSE.txt).
22 changes: 22 additions & 0 deletions amplify.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
version: 1
backend:
phases:
build:
commands:
- '# Execute Amplify CLI with the helper script'
- amplifyPush --simple
frontend:
phases:
preBuild:
commands:
- npm ci
build:
commands:
- npm run build
artifacts:
baseDirectory: build
files:
- '**/*'
cache:
paths:
- node_modules/**/*
19 changes: 19 additions & 0 deletions cfn-amplifyRole.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
AWSTemplateFormatVersion: "2010-09-09"
Resources:
AmplifyRole:
Type: 'AWS::IAM::Role'
Properties:
RoleName: amplifyconsole-basics4health-backend-role
Description: IAM Role to deploy amplify Basics for Health Project
AssumeRolePolicyDocument:
Version: "2012-10-17"
Statement:
- Effect: Allow
Principal:
Service:
- amplify.amazonaws.com
Action:
- 'sts:AssumeRole'
Path: /
ManagedPolicyArns:
- arn:aws:iam::aws:policy/AdministratorAccess-Amplify
23 changes: 23 additions & 0 deletions docs/ArchitectureDeepDive.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Backend and Frontend Stack Deep Dive

## Architecture

![Architecture diagram](../docs/images/architecture-diagram.png)

## Description

1. User launches the application from an EHR.

2. The selected patient's data is retrieved from the FHIR server along with the necessary authorization tokens.

3. The user signs-in to access the application through Amazon Cognito, which assigns them different permissions depending on if they are an administrator or not.

4. An API call is made to the GraphQL API by the app.

5. The GraphQL API call queries Amazon DynamoDB for the form name, version, and ID.

6. The result of the query is passed back from the API.

7. The result of the query is returned to the app.

8. The app uses the returned data to send a request to the FHIR server to retrieve the appropriate resource.
75 changes: 75 additions & 0 deletions docs/DeploymentGuide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# Requirements

Before you deploy, you must have the following accounts:

- [AWS Account](https://aws.amazon.com/account/)
- [GitHub Account](https://github.com/)

You must also have the following installed on your device:

- [Docker Desktop](https://www.docker.com/products/docker-desktop/)
- [Git](https://git-scm.com/downloads)
- [AWS CLI](https://aws.amazon.com/cli/)

Once you have downloaded docker desktop, follow the installation instructions for the FHIR dev sandbox [here](https://github.com/smart-on-fhir/smart-dev-sandbox).

# Clone The Repository

First, clone the GitHub repository onto your machine. To do this:

1. Create a folder on your computer to contain the project code.
2. For an Apple computer, open Terminal. If on a Windows machine, open Command Prompt or Windows Terminal. Enter into the folder you made using the command `cd path/to/folder`. To find the path to a folder on a Mac, right click on the folder and press `Get Info`, then select the whole text found under `Where:` and copy with ⌘C. On Windows (not WSL), enter into the folder on File Explorer and click on the path box (located to the left of the search bar), then copy the whole text that shows up.
3. Clone the github repository by entering the following:

```bash
git clone https://github.com/UBC-CIC/basics-for-health.git
```

The code should now be in the folder you created. Navigate into the folder containing the Amplify project by running the command:

```bash
cd basics-for-health
```

# Deployment

Before deploying the Amplify project we need to create an IAM Role that will give us the permissions needed to implement this solution. Run the following line of code:

```bash
aws cloudformation deploy --template-file cfn-amplifyRole.yaml --stack-name amplifyconsole-basics4health-backend-role --capabilities CAPABILITY_NAMED_IAM
```

If you have multiple AWS Profiles, specify one with sufficient admin permissions by appending the following text to the end of the command, replacing the profile name with the profile you would like to use for the solution.

```bash
--profile [PROFILE NAME]
```

This step creates an IAM role called **amplifyconsole-basics4health-backend-role** that will be used on the next step.

The **Deploy to Amplify Console** button will take you to your AWS console to deploy the front-end solution.

<a href="https://console.aws.amazon.com/amplify/home#/deploy?repo=https://github.com/UBC-CIC/basics-for-health">
<img src="https://oneclick.amplifyapp.com/button.svg" alt="Deploy to Amplify Console">
</a>

1. On the AWS console, select your region and click `Connect to GitHub`.
![alt text](images/deployment.png)
2. Authorize AWS Amplify with your GitHub account.
![alt text](images/deployment2.PNG)
3. Select the **amplifyconsole-basics4health-backend-role** we made previously for the deployment role, and then press `Save and Deploy`
![alt text](images/deployment3.png)
4. The deployment will take a few minutes. Wait until the status of **Verify** is green
![alt text](images/deployment4.png)
5. Next, on the left side menu, click on Rewrites and redirects and click the `Edit` button. Click and replace the first rule's **source address** (or add a rule if there is none) to `</^((?!\.(css|gif|ico|jpg|js|png|txt|svg|woff|ttf)$).)*$/>`. Replace the **target address** to `/index.html`, and replace the **type** to `200 (Rewrite)`. Add a second rule with the **same source and target address**, but change the **type** to `404 (Rewrite)`. Refer to [AWS's Page on Single Page Apps](https://docs.aws.amazon.com/amplify/latest/userguide/redirects.html#redirects-for-single-page-web-apps-spa) for further information on why that was necessary.

It should look like this once you are done:
![alt text](images/deployment5.png)

The app is now deployed!

If you wish to further contribute to this project, install the required packages and dependencies with the following command:

```bash
npm install
```
75 changes: 75 additions & 0 deletions docs/UserGuide.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# User Guide

**Before Continuing with this User Guide, please make sure you have deployed the frontend and backend stacks.**

- [Deployment Guides](./DeploymentGuide.md)

| Index | Description |
| :--------------------------------- | :------------------------------------- |
| [Docker](#docker) | Docker container for app launch |
| [Main Page](#main-page) | Fill out forms |
| [Upload Form](#upload-form) | Upload new / update existing forms |
| [Add Admin User](#add-admin-user) | Set other users as admins |

## Docker

**The application is configured to launch from an EHR. The docker container installed during the deployment guide simulates an EHR and is where the application will be launched from.**

Start the docker container as described [here](https://github.com/smart-on-fhir/smart-dev-sandbox).

Click on `Launch a SMART App`.
![alt text](images/user-guide.PNG)

Scroll down and enter the app URL in the `App Launch URL` field.
![alt text](images/user-guide2.PNG)

Log in as the provided practitioner and select a patient from the list. The sign in/sign up screen for the app will then be displayed.

## Main Page

**This will be the only page available to regular, non-admin users.**

When a user signs in, the first page shown will be the page for filling out forms.
![alt text](images/user-guide3.PNG)

There is a dropdown menu that will display all the forms that the user has uploaded or that has been assigned to them. Next to it is a spinbox that allows the user to pick the version of the form to render (if updates have been made to it). Clicking on `LOAD` after selecting a form and its version will render the form to be filled out.
![alt text](images/user-guide4.PNG)

If the form has been submitted before, the answers will also be loaded with it.

## Upload Form

This page allows admin users to either upload new forms or update existing ones.

When uploading a new one, a name for the form is required; this is what will be shown in the dropdown selection menu. There is another field (optional) that allows the user to enter the name of another user to give them access to the form as well.
![alt text](images/user-guide5.png)

When updating an existing one, the user must select the form they are updating from the dropdown menu.
![alt text](images/user-guide6.PNG)

To actually create these forms, online tools exist for building FHIR questionnaires. The one we used can be found [here](https://lhcformbuilder.nlm.nih.gov/previous/).
![alt text](images/user-guide7.PNG)

When adding questions, please use LOINC codes when possible.
![alt text](images/user-guide8.PNG)

After you are finished building your form, click `Export` to download it as a file; this is what will be uploaded to the application.

If updating an existing form, click `Import` and select the one you wish to edit. After you make your changes, download it again and upload it to the update page of the application.

## Add Admin User

This page allows the admin user to set other users as admins.
![alt text](images/user-guide9.PNG)

To set up the **first** admin account, you will need to do the following steps. (Note: this assumes the user has already signed up on the app)

1. On the [AWS online console](https://console.aws.amazon.com/console/home), enter `Cognito` in the search bar.
![alt text](images/admin-setup.png)
2. Click `Manage User Pools` and select the user pool that corresponds to the project name. The following screen will then be shown.
![alt text](images/admin-setup2.png)
3. On the left side menu, under General settings, click `Users and groups`. Select the user you wish to set as an admin.
![alt text](images/admin-setup3.png)
4. Click the `Add to group` button and select **Admins** from the drop down menu.
![alt text](images/admin-setup4.png)

Binary file added docs/images/admin-setup.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/admin-setup2.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/admin-setup3.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/admin-setup4.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/architecture-diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/deployment.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/deployment2.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/deployment5.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide2.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide3.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide4.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide5.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide6.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide7.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide8.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/user-guide9.PNG
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion src/Components/navbar.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import Sidebar from './sidebar';
import { Auth } from 'aws-amplify';
import { useNavigate } from 'react-router-dom';
import { useEffect } from "react";
import AdminStatus from "../Helpers/adminStatus";
import AdminStatus from "../adminStatus";

export default function Navbar() {
const [admin, setAdmin] = useState(false);
Expand Down
2 changes: 1 addition & 1 deletion src/Pages/form.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import { useEffect, useState } from 'react';
import axios from 'axios';
import { Alert, Collapse, Button, FormControl, InputLabel, Select, MenuItem, TextField } from '@mui/material';
import SendIcon from '@mui/icons-material/Send';
import AdminStatus from '../Helpers/adminStatus';
import AdminStatus from '../adminStatus';
import { Auth, API, graphqlOperation } from 'aws-amplify';
import { listForms, getFormByName } from '../graphql/queries';

Expand Down
File renamed without changes.

0 comments on commit f1a8c81

Please sign in to comment.