docs: Update docs, Third party file & diagram (#207)

Author: rsmayda

CODE_OF_CONDUCT.md

@@ -1,5 +1,3 @@
 ## Code of Conduct
 
-This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
-For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
-[email protected] with any additional questions or comments.
+This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct). For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact [email protected] with any additional questions or comments.

CUSTOMIZE.md

@@ -45,19 +45,20 @@ This FHIR Works on AWS deployment supports role based access control (RBAC) for
 
 To assign users to specific user groups please log into the AWS console and navigate to the Cognito service. Once there select on your FHIR User Pool and find the user you want to modify. From there add that user to the desired user group.
 
-## CORS customization			
-			
-The FHIR Works on AWS deployment can be customized to provide CORS support for brower-based applications.  The following configuration steps are required:
-* Supply a [CorsOptions](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/cors/index.d.ts) configuration when building the [serverless router](src/index.ts).  For example
-    ```
-    const corsOptions: CorsOptions = {...};
-    ...
-    generateServerlessRouter(fhirConfig, genericResources, corsOptions)
-    ```
-    Please see the available [configuration options](https://www.npmjs.com/package/cors#configuration-options).
-			
-* For pre-flight request support, add an OPTIONS method to the API Gateway `{proxy+}` route within the Serverless template.  The request should be handled by the Lambda handler.  The method should not use authorization.
-* If using a custom authorizer, then rejected requests also need to provide CORS headers, otherwise it is tricky to interpret the unauthorized response in the browser.  The following [blog](https://www.serverless.com/blog/cors-api-gateway-survival-guide) describes how a `GatewayResponse` resource may be added to the Serverless template to provide these headers.
+## CORS customization
+
+The FHIR Works on AWS deployment can be customized to provide CORS support for browser-based applications. The following configuration steps are required:
+
+
+- Supply a [CorsOptions](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/cors/index.d.ts) configuration when building the [serverless router](src/index.ts). For example
+  ```ts
+  const corsOptions: CorsOptions = {...};
+  ...
+  generateServerlessRouter(fhirConfig, genericResources, corsOptions)
+  ```
+  Please see the available [configuration options](https://www.npmjs.com/package/cors#configuration-options).
+- For pre-flight request support, add an OPTIONS method to the API Gateway `{proxy+}` route within the Serverless template. The request should be handled by the Lambda handler. The method should not use authorization.
+- If using a custom authorizer, then rejected requests also need to provide CORS headers, otherwise it is tricky to interpret the unauthorized response in the browser. The following [blog](https://www.serverless.com/blog/cors-api-gateway-survival-guide) describes how a `GatewayResponse` resource may be added to the Serverless template to provide these headers.
 
 ## Supporting other FHIR implementation guides or profiles
 

DEVELOPMENT.md

@@ -11,7 +11,7 @@ In this guide we will go over how to develop and run the code locally. We will a
 
 Please download all the `fhir-works-on-aws` package and place them inside one directory. Your parent directory should have these folders inside of them
 
-```
+```sh
 ./fhir-works-on-aws-deployment
 ./fhir-works-on-aws-interface
 ./fhir-works-on-aws-persistence-ddb
@@ -53,23 +53,23 @@ Run this command to deploy your code to AWS:
 
 ## Troubleshooting
 
-#### Runtime.ImportModuleError on other FWoA package
+### Runtime.ImportModuleError on other FWoA package
 
-If you run into error type `Runtime.ImportModuleError` with error message stating the offending method comes from another FWoA package, check the versions of local FWoA packages match the versions specified in `package.json`. If you see a mismatch, update the version number in `package.json` to match your local packages and commit the change should fix the issue. 
+If you run into error type `Runtime.ImportModuleError` with error message stating the offending method comes from another FWoA package, check the versions of local FWoA packages match the versions specified in `package.json`. If you see a mismatch, update the version number in `package.json` to match your local packages and commit the change should fix the issue.
 
-As an example, if your local packages have versions specified as: 
+As an example, if your local packages have versions specified as:
 
-```
+```sh
 [email protected]+97caac97
 [email protected]+7f1d59ed
 [email protected]+60259b47
 [email protected]+75ad6c2c
 [email protected]+ceec8029
-``` 
+```
 
-Then `package.json` should have the same versions specified as well: 
+Then `package.json` should have the same versions specified as well:
 
-```
+```json
 "dependencies": {
     "aws-sdk": "^2.785.0",
     "axios": "^0.21.1",
@@ -82,5 +82,4 @@ Then `package.json` should have the same versions specified as well:
   },
 ```
 
-If you have a mismatch in `package.json`, say `fhir-works-on-aws-routing` was set to `4.1.0` instead of `4.0.0`. An error message 
-
+If you have a mismatch in `package.json`, say `fhir-works-on-aws-routing` was set to `4.1.0` instead of `4.0.0`. An error message

INSTALL.md

@@ -148,11 +148,12 @@ docker rm ${container_id}
 - Windows installation has been tested when run from Windows PowerShell for AWS. Running the install script from a regular PowerShell may fail.
 - Cloud9 installation may fail (when using Amazon Linux 2 instance) with the following error message:
 
-```
+```sh
 Error: Package: 1:npm-3.10.10-1.6.17.1.1.el7.x86_64 (@epel)
            Requires: nodejs = 1:6.17.1-1.el7
 (additional lines are omitted)
 ```
+
 If you encounter this error run `sudo yum erase npm` and then re-run installation script.
 
 ## Manual installation prerequisites

README.md

@@ -1,6 +1,6 @@
 # fhir-works-on-aws-deployment
 
-FHIR Works on AWS is a framework to deploy a [FHIR](https://www.hl7.org/fhir/overview.html) server on AWS. This package is an example implementation of this framework. The power of this framework is being able to customize and add in additional FHIR functionality for your unique use-case. An example of this, is this implementation uses [DynamoDB](https://github.com/awslabs/fhir-works-on-aws-persistence-ddb). Say you don't want to use DynamoDB, you could implement your own persistence component and plug it into your deployment package. With FHIR Works on AWS you control how your FHIR server will work!
+FHIR Works on AWS is a framework to deploy a [FHIR](https://www.hl7.org/fhir/overview.html) server on AWS. This package is an example implementation of this framework. The power of this framework is being able to customize and add in additional FHIR functionality for your unique use-case. An example of this, is this deployment uses [Cognito and role based access control](https://github.com/awslabs/fhir-works-on-aws-authz-rbac). Say you would rather support [SMART on FHIR](https://github.com/awslabs/fhir-works-on-aws-authz-smart), you could swap out the authorization component and plug it into your deployment package. A sample of this swap out can be found on the [smart-mainline branch](https://github.com/awslabs/fhir-works-on-aws-deployment/tree/smart-mainline) of this repository. With FHIR Works on AWS you control how your FHIR server will work!
 
 ## Capabilities
 
@@ -13,7 +13,7 @@ This deployment implementation utilizes Lambda, DynamoDB, S3 and Elasticsearch t
 
 ## Quick start/installation
 
-Do you want to just try it out? Please follow the instructions below:
+The easiest and quickest way to experience FHIR Works on AWS is through [AWS solutions](https://aws.amazon.com/solutions/implementations/fhir-works-on-aws/). If you are interested in modifying the code and setting up your developer environment we recommend you following the below instructions:
 
 ### Download
 
@@ -31,11 +31,10 @@ git clone https://github.com/awslabs/fhir-works-on-aws-deployment.git
 - [Windows](./INSTALL.md#windows-installation)
 - [Docker](./INSTALL.md#docker-installation)
 
-
 ### Development
 
 [Instructions for making local code changes](./DEVELOPMENT.md)
- 
+
 ## Architecture
 
 The system architecture consists of multiple layers of AWS serverless services. The endpoint is hosted using API Gateway. The database and storage layer consists of Amazon DynamoDB and S3, with Elasticsearch as the search index for the data written to DynamoDB. The endpoint is secured by API keys and Cognito for user-level authentication and user-group authorization. The diagram below shows the FHIR server’s system architecture components and how they are related.
@@ -97,10 +96,10 @@ Instructions for importing the environment JSON is located [here](https://thinks
 
 The variables required in the POSTMAN collection can be found in `Info_Output.yml` or by running `serverless info --verbose`
 
-API_URL: from Service Information:endpoints: ANY
-API_KEY: from Service Information: api keys: developer-key
-CLIENT_ID: from Stack Outputs: UserPoolAppClientId 
-AUTH_URL: `https://<CLIENT_ID>.auth.<REGION>.amazoncognito.com/oauth2/authorize`, 
+- API_URL: from Service Information:endpoints: ANY
+- API_KEY: from Service Information: api keys: developer-key
+- CLIENT_ID: from Stack Outputs: UserPoolAppClientId
+- AUTH_URL: `https://<CLIENT_ID>.auth.<REGION>.amazoncognito.com/oauth2/authorize`
 
 To know what all this FHIR API supports please use the `GET Metadata` postman to generate a [Capability Statement](https://www.hl7.org/fhir/capabilitystatement.html).
 
@@ -123,7 +122,7 @@ In order to access the FHIR API, an `ACCESS_TOKEN` is required. This can be obta
 4. A sign in page should pop up where you should put in your username and password (if you don't know it look at the [init-auth.py](scripts\init-auth.py) script)
 5. Once signed in the access token will be set and you will have access for ~1 hour
 
-#### Retrieving an access token via script  (scope = aws.cognito.signin.user.admin)
+#### Retrieving an access token via script (scope = aws.cognito.signin.user.admin)
 
 A Cognito OAuth access token can be obtained using the following command substituting all variables with their values from `INFO_OUTPUT.yml` or the previously mentioned `serverless info --verbose` command.
 
@@ -139,25 +138,24 @@ For Mac:
 python3 scripts/init-auth.py <CLIENT_ID> <REGION>
 ```
 
-The return value is an `ACCESS_TOKEN` that can be used to hit the FHIR API without going through the Oauth Sign In page. In POSTMAN, instead of clicking the `Get New Access Token` button, you can paste the `ACCESS_TOKEN` value into the Available Tokens text field.  
+The return value is an `ACCESS_TOKEN` that can be used to hit the FHIR API without going through the Oauth Sign In page. In POSTMAN, instead of clicking the `Get New Access Token` button, you can paste the `ACCESS_TOKEN` value into the Available Tokens text field.
 
 ### Accessing Binary resources
 
 Binary resources are FHIR resources that consist of binary/unstructured data of any kind. This could be X-rays, PDF, video or other files. This implementation of the FHIR API has a dependency on the API Gateway and Lambda services, which currently have limitations in request/response sizes of 10MB and 6MB respectively. This size limitation forced us to look for a workaround. The workaround is a hybrid approach of storing a Binary resource’s _metadata_ in DynamoDB and using S3's get/putPreSignedUrl APIs. So in your requests to the FHIR API you will store/get the Binary's _metadata_ from DynamoDB and in the response object it will also contain a pre-signed S3 URL, which should be used to interact directly with the Binary file.
 
 ### Testing Bulk Data Export
 
-Bulk Export allows you to export all of your data from DDB to S3. We currently only support [System Level](https://hl7.org/fhir/uv/bulkdata/export/index.html#endpoint---system-level-export) export. 
-For more information about Bulk Export, please refer to this [implementation guide](https://hl7.org/fhir/uv/bulkdata/export/index.html).
+Bulk Export allows you to export all of your data from DDB to S3. We currently only support [System Level](https://hl7.org/fhir/uv/bulkdata/export/index.html#endpoint---system-level-export) export. For more information about Bulk Export, please refer to this [implementation guide](https://hl7.org/fhir/uv/bulkdata/export/index.html).
 
-The easiest way to test this feature on FHIR Works on AWS is to make API requests using the provided [Fhir.postman_collection.json](./postman/Fhir.postman_collection.json). 
+The easiest way to test this feature on FHIR Works on AWS is to make API requests using the provided [Fhir.postman_collection.json](./postman/Fhir.postman_collection.json).
 
-1. In the collection, under the  "Export" folder, use `GET System Export` request to initiate an Export request.
-2. In the response, check the header field `Content-Location` for a URL. The url should be in the format `<base-url>/$export/<jobId>`. 
-3. To get the status of the export job, in the "Export" folder used the `GET System Job Status` request. That request will ask for the `jobId` value from step 2. 
+1. In the collection, under the "Export" folder, use `GET System Export` request to initiate an Export request.
+2. In the response, check the header field `Content-Location` for a URL. The url should be in the format `<base-url>/$export/<jobId>`.
+3. To get the status of the export job, in the "Export" folder used the `GET System Job Status` request. That request will ask for the `jobId` value from step 2.
 4. Check the response that is returned from `GET System Job Status`. If the job is in progress you will see a header with the field `x-progress: in-progress`. Keep polling that URL until the job is complete. Once the job is complete you'll get a JSON body with presigned S3 URLs of your exported data. You can download the exported data using those URLs.
- 
-Note: To cancel an export job that is in progress, you can use the `Cancel Export Job` request in the "Export" folder in POSTMAN collections.  
+
+Note: To cancel an export job that is in progress, you can use the `Cancel Export Job` request in the "Export" folder in POSTMAN collections.
 
 #### Postman (recommended)