fasten-onprem/CONTRIBUTING.md

> This doc is a WIP and will be expanded shortly.
> 
> In the meantime, please consider looking at the extensive docs in the [Fasten Docs Repository](https://github.com/fastenhealth/docs/tree/main/technical)

# Tech Stack

Fasten is made up of a handful of different components. Here's a summary of the technologies & languages used in Fasten:

**Frontend**
- NodeJS `v18.9.0`
- Yarn `1.22.19`
- Angular `v14.1.3`

**Backend**
- Go `v1.18.3`

**Misc**
- Docker `v20.10.17`

## Setup

If you're on a Mac, you can run the following commands to install the necessary software to get setup:

```bash
brew install node
npm install -g @angular/cli@14.1.3
npm install -g yarn

brew install go

brew install docker

# Frontend tests run with ChromeHeadless browser.
brew install --cask google-chrome

# Go specific tools
go install github.com/gzuidhof/tygo@latest
```

# Running Tests

Before making changes to Fasten, you'll want to run the test suites to ensure that your environment is setup correctly:

```bash
make test

# if you only want to run the frontend tests (Angular), you can run:
make test-frontend

# alternatively, if you only care about backend (Go) tests, you can run:
make test-backend
```

**Note**: Running backend tests may take awhile to complete the first time you run

# Start Development Environment

To run Fasten from source, you'll need to create 2 separate processes:

- Angular Frontend
- Go Backend

First we'll create a development config file (`config.dev.yaml`)

```yaml
version: 1
web:
  listen:
    port: 9090
    host: 0.0.0.0
    basepath: ''
  src:
    frontend:
      path: ./dist
database:
  location: 'fasten.db'
cache:
  location: ''
log:
  file: '' #absolute or relative paths allowed, eg. web.log
  level: INFO
```

Next we'll start the processes described above:

```bash

# In terminal #1, run the following
make build-frontend-[sandbox|prod]
# eg. make build-frontend-sandbox

# In terminal #2, run the following
make serve-backend

```

_Note_: Fasten can run in 2 modes: sandbox or production (prod). In sandbox mode, it can only communicate with test servers (full of synthetic health data).

Now you can open a browser to `http://localhost:9090` to see the Fasten UI. 

## Important URL's 

The following URL's and credentials may be helpful as you're developing

- http://localhost:9090/web/dashboard - WebUI

### Credentials
- WebUI: 
  - username: `testuser`
  - password: `testuser`

# Source Code Folder Structure

The Fasten source code is organized into a handful of important folders, which we'll describe below:

## Frontend

```
├── frontend
│   ├── src
│   │   ├── app
│   │   │   ├── app-routing.module.ts
│   │   │   ├── app.component.html
│   │   │   ├── app.component.scss
│   │   │   ├── app.component.spec.ts
│   │   │   ├── app.component.ts
│   │   │   ├── app.module.ts
│   │   │   ├── components                        # contains shared/partial components reused on multiple pages.
│   │   │   │   ├── components-sidebar
│   │   │   │   ├── footer
│   │   │   │   ├── header
│   │   │   │   ├── list-fallback-resource
│   │   │   │   ├── list-generic-resource         # A component containing a table view for every FHIR resource
│   │   │   │   ├── list-patient
│   │   │   │   ├── resource-list                 # Thin shim which populates template depending on FHIR resource type
│   │   │   │   ├── toast                         # Toast/notification component
│   │   │   │   └── utilities-sidebar
│   │   │   ├── models                            # contains classes for communicating with API's and transfering data between pages. 
│   │   │   ├── pages
│   │   │   │   ├── auth-signin                   # Login/Signin page
│   │   │   │   ├── auth-signup                   # Signup page
│   │   │   │   ├── dashboard                     # Dashboard, visible after logging in
│   │   │   │   ├── medical-sources               # Medical Provider connection page
│   │   │   │   ├── patient
│   │   │   │   ├── resource-detail               # Page displaying detailed information about FHIR resource
│   │   │   │   └── source-detail                 # 2 column page displaying FHIR counts, and table listing FHIR resources for selected type
│   │   │   ├── services
│   │   │   │   ├── auth-interceptor.service.ts   # service that looks for 401/403 API responses and triggers Logout
│   │   │   │   ├── is-authenticated-auth-guard.ts    # service that checks if user is logged in
│   │   │   │   ├── fasten-api.service.ts         # api service, used to commnunicate with Go backend (WILL BE REMOVED)
│   │   │   │   ├── fasten-db.service.ts          # db service, used to communicate with CouchDB database
│   │   │   │   ├── lighthouse.service.ts         # api service, used to communicate with auth-gateway (Lighthouse)
│   │   │   │   └── toast.service.ts              # notifications service, used to send notifications
│   │   │   └── workers
│   │   │       ├── queue.service.spec.ts
│   │   │       ├── queue.service.ts              # queue service, used to coordinate background work
│   │   │       └── source-sync.worker.ts         # background job (web-worker) that syncs all FHIR resources from healthcare provider
│   │   ├── lib                                   # root directory for libraries
│   │   │   ├── README.md
│   │   │   ├── conduit                           # Conduit Library - HealthCare provider communication layer (FHIR protocol)
│   │   │   │   ├── fhir                          # contains healthcare provider specific FHIR clients
│   │   │   ├── database                          # Database Library - PouchDB/CouchDB client, compatible with web-worker and browser env
│   │   │   │   ├── plugins
│   │   │   │   └── pouchdb_repository.ts          
│   │   │   ├── models
│   │   │   │   ├── database                      # Classes used to store data in CouchDB
│   │   │   │   ├── fasten                        
│   │   │   │   └── lighthouse                    # Classes used to communicate with Lighthouse API
│   │   │   └── utils
│   │   ├── styles.scss                           # Main sylesheet
```

## Backend

The backend is incredibly simple (by design). The hope is to remove it completely if possible, allowing Fasten to be served by 
a CDN or minimal Nginx deployment. 

```tree
├── backend
│   ├── cmd
│   └── pkg
│       ├── config
│       ├── database                  # contains CouchDB client, allowing creation of new Users (and associated databases)
│       ├── errors
│       ├── models
│       └── web
│           ├── handler               # contains code for API endpoints
│           │   ├── auth.go           # authentication endpoints (create new user)
│           │   ├── cors_proxy.go     # CORS proxy/relay for communicating with healthcare providers who do not support CORS
│           │   ├── couchdb_proxy.go  # reverse proxy for CouchDB api, allowing for database API to be exposed (with limitations)
│           │   └── metadata.go       # API endpoint returning metadata for healthcare providers
```

## Distribution/Docker

```tree
├── docker-compose.yml                  # docker-compose file which can be used to compile and run "all-in-one" image
├── Dockerfile                          # dockerfile for "all-in-one" image, containing frontend, backend & database
├── docker
│   ├── README.md 
│   ├── couchdb                               
│   │   ├── Dockerfile                  # dockerfile for "couchdb" only image, used for development
│   │   └── local.ini
│   └── rootfs                          # filesystem configs, used in Dockerfiles to setup s6-overlay service manager
│       └── etc
│           ├── cont-init.d
│           │   ├── 01-timezone
│           │   └── 50-couchdb-init
│           └── services.d
│               ├── couchdb
│               └── fasten

```

# FAQ

### How do I run individual frontend tests?

From the `frontend` directory, you can run `ng test` with the `--include` argument.

```bash
ng test --include='**/badge.component.spec.ts'
ng test --include='lib/**/*.spec.ts'
```

### How do I change the default encryption key and admin credentials
- FASTEN_ISSUER_JWT_KEY


### Generate JWT for local use
```bash
curl -X POST http://localhost:9090/api/auth/signup -H 'Content-Type: application/json' -d '{"username":"user1","password":"user1"}'

curl -X POST http://localhost:9090/api/auth/signin -H 'Content-Type: application/json' -d '{"username":"user1","password":"user1"}'


curl -H "Authorization: Bearer ${JWT_TOKEN_HERE}" http://localhost:5984/_session

```


# How do I work with Storybook?

[Storybook](https://storybook.js.org) allows development and testing of frontend components in isolation.
When running the Storybook server, each defined story can be viewed and interacted with on it's own allowing for defining and testing of various states and conditions.

In order to run the Storybook server, run the following command and open the url provided:

```bash
make serve-storybook
```

If you only want to verify that all stories build properly (a check that is run on commits and PRs), you can run the following command:

```bash
make build-storybook
```


# Access Encrypted SQLite Database with IntelliJ

- Download the latest `sqlite-jdbc-crypt` jar from https://github.com/Willena/sqlite-jdbc-crypt/releases
- Open IntelliJ -> Data Source Properties -> Driver Tab
- Find & Select `Sqlite` -> Right Click -> Duplicate
- Rename to `Sqlite (Encrypted)`
- Find `Driver Files` -> Select `sqlite-jdbc-crypt` jar that you downloaded previously
- Remove `Xerial Sqlite JDBC` jar
- Click `Apply` -> Click `OK`
- Create New Data Source -> Select `Sqlite (Encrypted)` -> Change Connection Type to `Url only`
- Specify the following connection url: `jdbc:sqlite:fasten.db?cipher=sqlcipher&legacy=3&hmac_use=0&kdf_iter=4000&legacy_page_size=1024&key=123456789012345678901234567890`
- Replace `key` with the encryption key specified in your config file (`database.encryption_key`)
- Click `Test Connection` -> Should be successful
- Click `Apply` -> Click `OK`

# Flush SQLite Write-Ahead-Log (WAL) to Database

```sqlite
PRAGMA wal_checkpoint(TRUNCATE);
```

See: https://sqlite.org/forum/info/fefd56014e2135589ea57825b0e2aa3e2df5daf53b5e41aa6a9d8f0c29d0b8e5
TODO: check if https://www.sqlite.org/pragma.html#pragma_wal_checkpoint can be used to do this automatically.