# Bachelor Thesis: Medwings

This repository contains the software, research data and final thesis I worked on
as part of my Computer Science degree at TU Braunschweig.

Over the course of three months, my work examined the current state of research in mobile patient deterioration monitoring,
and involved the development and evaluation of a novel software system called Medwings, which is an
early warning system for high-risk patients outside of direct medical supervision, using smart medical sensors in combination with
automated early warning score calculations.

Following the conception and development of the software, the system underwent a usability trial
and rigorous performance analysis.

The system was built as a responsive web application with the following technologies:
- **Django** for core business logic and server side rendering of the UI:
    - **Django REST framework**: API for health data updates
    - **OAuth 2.0**: patient data exchange with the Withings Cloud
    - **TailwindCSS**: UI layouts and styling
- **Docker** for deployment and interconnection of microservices:
    - **PostgreSQL**: database for health records
    - **Gotify**: Android Push Notification Service
    - **Caddy**: Web Server, Request Router, Load Balancer

With this work, I completed my degree and achieved the highest attainable mark (1.0) for a thesis,
and was offered a unique opportunity to continue my research in this area.
For more details about Medwings, its architecture, the development process and the in-depth evaluation and usability
study of the system, you can **[read the full paper here](./docs/thesis/thesis.pdf)**.

## Overview

> **Clinical Deterioration**: A measurable overall decline in a patient's vital functions, preceeding critical adverse outcomes.

Clinical deterioration can be detected up to 12 hours in advance of critical patient outcomes, such as
the need for ICU admission or even death. *Early warning scores*, such as the Modified Early Warning Score (**MEWS**),
have been in use internationally in hospitals to assess and monitor high-risk patients, and have proven to be
an effective predictor for deterioration.

To calculate an early warning score, or MEWS specifically, several vital parameters of the patient are measured and
scored individually. The individual scores are then added together to produce the final MEWS, which gives a clear
indication of the patient's risk of deterioration. The following table shows the vital parameters and scoring for MEWS:

![MEWS Scoring Table](./docs/figures/mews-calculation-table.png)

Using tradtitional, expensive and immobile vitals monitoring devices, early warning scores are well established and widely used.
But what about at home or on the go? With recent advances in smart medical sensor technologies, predicting patient
deterioration could be possible even outside of medical care facilities, using less expensive equipment and carried out by
the patient autonomously. My research explored this approach through the implementation and evaluation of a mobile early
deterioration warning system: MEDWingS.

### MEDWingS

MEDWingS, the **M**obile **E**arly **D**eterioration **W**arn**ing** **S**ystem, is a mobile-first web application coupled
with a selection of smart medical devices and a notification service. Prompted by periodic notifications on their phone,
patients are asked to visit the web-UI, followed by recording their vital parameters using each one of the following devices:

- **Withings ScanWatch**: a smart watch capable of measuring heart rate and blood oxygen levels
- **Withings BPM Core**: a smart blood pressure meter
- **Withings Thermo**: a smart thermometer

These devices are shown the following picture:

![Withings Smart Medical Devices](./docs/figures/withings-devices.png)

Some UI screenshots of this process are shown here:

![Medwings Measurement Screenshots](./docs/figures/medwings-measurement-screenshots.png)

Following the successful measurement using all three devices, Medwings retrieves the recorded vitals data from the Withings API,
processes it, calculating the patient's MEWS, and stores the results. The patient user is given feedback through the UI and, should
the resulting MEWS be at a level of concern, an alert is generated.

#### Technical Details

Medwings was built using the Django framework, and uses a [Gotify Notfication Server](https://gotify.net/) to send mobile
notifications. It communicates with the Withings Health Data Cloud via the RESTful Withings API, using OAuth2 for authentication of
requests and to link Withings user accounts to Medwings. The dedicated Gotify Server used by Medwings is also controlled via
its own REST API.

The Medwings application itself is split into the following modules, each handling a specific responsibility:

- [core](./app/core/): globally shared files and application-wide configuration
- [authentication](./app/authentication/): Medwings user and login/logout management
- [medwings](./app/medwings/): everything related to vitals data processing, storage and MEWS calculation
- [gotify](./app/gotify/): interfaces to the notification server
- [withings](./app/withings/): interfaces to the Withings API

You can read more about each module and its functionality in each section mentioned above.

# Development Guide

This section contains some notes and references for Medwings developers.

## Sensitive Configuration Data

To avoid leaking sensitive configuration data, such as database passwords or API keys, all such values are stored in the
`.env`-file.

Prior to running the application, you must create a file called `.env` in the project root.
The file contains the following environment variables:

```conf
TIMEZONE=Europe/Berlin
DJANGO_DEBUG_MODE=false
DJANGO_SECRET_KEY=abc123mySecret
PG_NAME=medwings
PG_USER=medwings
PG_PASSWORD=secret
PG_HOST=medwings-postgres
PG_PORT=5432
GOTIFY_USER=gotify
GOTIFY_PASSWORD=secret
GOTIFY_HOST=medwings-gotify
GOTIFY_PUBLIC_URL=https://notifications.medwings.example.com/
WITHINGS_CLIENT_ID=abc123myClientId
WITHINGS_CLIENT_SECRET=abc123myClientSecret
```

You should set the values of the following variables:

| variable | description | value |
|----------|-------------|-------|
| DJANGO_DEBUG_MODE | whether or not to enable Django's debug mode | 'true' during development and 'false' in production |
| DJANGO_SECRET_KEY | private session secret | a random string of 64 characters or more |
| PG_PASSWORD | password for the PostgreSQL admin user | a random string of 32 characters or more |
| GOTIFY_USER | name of the Gotify admin user | a random string of 32 characters or more |
| GOTIFY_PASSWORD | password for the Gotify admin user | a random string of 32 characters or more |
| GOTIFY_PUBLIC_URL | URL where your public Gotify server can be reached | this depends on your deployment environment |
| WITHINGS_CLIENT_ID | Your Withings API client id | see [Withings API](./app/withings/README.md#api-access) |
| WITHINGS_CLIENT_SECRET | Your Withings API client secret | see [Withings API](./app/withings/README.md#api-access) |


## Starting the dev environment

Once your environment vars are set up, you can run the backend and webserver, by running the following command:

```bash
sudo docker-compose -f development.docker-compose.yml up --force-recreate --build --remove-orphans
```

In a separate terminal, you should also start the frontend asset bundler:

```bash
npm run start
```

It supports file watching and automatic recompilation of the project's CSS and JS bundle.

### Running commands inside the container

To run commands inside the django container, run the following:
```bash
sudo docker exec -itu django medwings-django <command>
```

Run database migrations inside the running container like so:

```bash
sudo docker exec -itu django medwings-django python manage.py migrate
```

To enter django's interactive shell, run:
```bash
sudo docker exec -itu django medwings-django python manage.py shell
```