docs: flesh out README

.gitignore

@@ -29,7 +29,9 @@
 **/*.out
 **/*.run.xml
 docs/proposal/*.pdf
+!docs/proposal/proposal.pdf
 docs/thesis/*.pdf
+!docs/thesis/thesis.pdf
 
 # Drawio backup and lock files
 **/*.drawio.bkp

README.md

@@ -1,25 +1,88 @@
-# MEDWings
+# Bachelor Thesis: Medwings
 
-Medwings is the *Mobile Early Deterioration Warning System*.
-It is a proof of concept for a remote patient monitoring system, designed for use by elevated-risk patients
-outside of direct medical supervision, such as at home or on the go.
+This repository contains the software, research data and final thesis I worked on
+as part of my Computer Science degree at TU Braunschweig.
 
-The application utilizes smart medical devices to access vitals data gathered by users remotely.
-Data is aggregated, and a clinical early warning score is calculated based on the readings.
+My research examined the current state of research in mobile patient deterioration monitoring,
+and introduced a novel software system, which acts as an early warning system for high-risk patients
+outside of direct medical supervision by utilising 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 Medwings application is split into different modules, each handling a specific responsibility:
+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.
 
-- [core](./app/core/README.md): global files and configuration
-- [authentication](./app/authentication/README.md): user creation and login/logout management
-- [medwings](./app/medwings/README.md): everything related to vitals data and MEWS calculation
-- [gotify](./app/gotify/README.md): interfaces to the notification server
-- [withings](./app/withings/README.md): interfaces to the Withings API
+## 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 is split itself 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
+#### Further Reading
 
-### Sensitive Configuration Data
+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 [complete paper here](/docs/thesis/thesis.pdf).
+
+# 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.
@@ -58,7 +121,7 @@ You should set the values of the following variables:
 | WITHINGS_CLIENT_SECRET | Your Withings API client secret | see [Withings API](./app/withings/README.md#api-access) |
 
 
-### Starting the dev environment
+## Starting the dev environment
 
 Once your environment vars are set up, you can run the backend and webserver, by running the following command:
 
@@ -74,7 +137,7 @@ npm run start
 
 It supports file watching and automatic recompilation of the project's CSS and JS bundle.
 
-#### Running commands inside the container
+### Running commands inside the container
 
 To run commands inside the django container, run the following:
 ```bash

docs/thesis/thesis.tex

@@ -1463,7 +1463,7 @@ With the help of the trial data, the developed software system should be evaluat
     \vspace{2cm}
     Braunschweig, 12.09.2023 \\
     \vspace{0.5cm}
-    \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/admin/signature.png}
+    \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
 \end{raggedleft}
 
 \newpage
@@ -1481,7 +1481,23 @@ Ferner versichere ich, dass es sich hier um eine Originalarbeit handelt, die noc
     \vspace{2cm}
     Braunschweig, 12.09.2023 \\
     \vspace{0.5cm}
-    \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/admin/signature.png}
+    \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
+\end{raggedleft}
+
+\newpage
+\section*{Erklärung zur Abgabe der gedruckten Abschlussarbeit}
+\addcontentsline{toc}{section}{Erklärung zur Abgabe der gedruckten Abschlussarbeit}
+
+Hiermit versichere ich, dass die vorliegende gedruckte Abschlussarbeit
+mit der elektronisch abgegebenen (hochgeladenen) Abschlussarbeit exakt
+übereinstimmt und dass ich keine unerlaubten Änderungen vorgenommen
+habe.
+
+\begin{raggedleft}
+    \vspace{2cm}
+    Braunschweig, 12.09.2023 \\
+    \vspace{0.5cm}
+    \hspace*{\fill}\includegraphics[height=2.5cm]{/home/ulinja/work/lwe/templates/graphics/written-signature.png}
 \end{raggedleft}
 
 \end{document}