From cb975c51b3c046f81dede2ac2ab907ed36e97bf1 Mon Sep 17 00:00:00 2001
From: Erik Harding <erik@praekelt.org>
Date: Wed, 24 Apr 2024 13:40:17 +0200
Subject: [PATCH] Update docs

---
 CHANGELOG.rst              |  2 ++
 docs/apps/randomisation.md | 30 ++++++++++++++++++++++++++++++
 docs/index.rst             |  1 +
 3 files changed, 33 insertions(+)
 create mode 100644 docs/apps/randomisation.md

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index c920f84..949cd6a 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -3,6 +3,8 @@ VERSIONS
 
 Next Release
 ------------
+Sidekick: Upgrade django to 4.2.11 and djangorestframework to 3.15.1
+Added new randomisation app
 
 1.10.6
 ------------
diff --git a/docs/apps/randomisation.md b/docs/apps/randomisation.md
new file mode 100644
index 0000000..3383947
--- /dev/null
+++ b/docs/apps/randomisation.md
@@ -0,0 +1,30 @@
+# Randomisation
+
+This app is used to configure randomisation strategies that can be used in studies. Currently we only have stratification implemented but we can add other strategy types at a later stage.
+
+### Models
+
+- `Strata`: To configure strata and their valid options.
+- `Strategy`: To configure the randomisation strategy which consists of stratas and arms.
+- `Arm`: Study arm that gets linked to a strategy, has a weight field that defaults to one, we use this in the randomisation to determine how often this arm will be selected.
+- `StrataOption`: Options linked to strata. We use this to validate data we receive.
+- `StrataMatrix`: To keep record of strata and which arms we need to return.
+
+### API
+
+These endpoint are both POST requests and have the same input format.
+
+Example request body if we configured stratas for gender and province:
+```
+{
+	"gender": "male",
+	"province": "WC"
+}
+```
+
+- `<int:strategy_id>/validate_strata_data/`: To check if strata data is valid without returning a arm. We use this to know we can request consent from the user, if they consent we use the `get_random_arm` endpoint to get a arm.
+	- Valid response: `200 {"valid": true}`
+	- Invalid response: `200 {"valid": false, "error": "<reason for not being valid>"}`
+- `<int:strategy_id>/get_random_arm/`: To get a random arm for the strata data provided.
+	- Successful response: `200 {"arm": "test arm"}`
+	- Error response: `400 {"error":"<validation errors>"}`
diff --git a/docs/index.rst b/docs/index.rst
index 4f91d7b..423b7d5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@
    apps/redcap.md
    apps/transferto.md
    apps/recruit.md
+   apps/randomisation.md
 
    ways-of-working.md