docs(website): add paragraph to Authorization in root readme, adapt r…

…untime_view.md and descriptions

README.md

@@ -38,13 +38,29 @@ export DOCKER_DEFAULT_PLATFORM=linux/amd64
 ```
 
 ## Authorization
+
+### User management
+
 We use keycloak for authorization. The keycloak instance is deployed in the `loculus` namespace and exposed to the outside either under `localhost:8083` or `authentication.[your-argo-cd-path]`. The keycloak instance is configured with a realm called `loculusRealm` and a client called `test-cli`. The realm is configured to use the exposed url of keycloak as a [frontend url](https://www.keycloak.org/server/hostname).
 For testing we added multiple users to the realm. The users are:
 - `admin` with password `admin` (login under `your-exposed-keycloak-url/admin/master/console/`)
 - `testuser` with password `testuser` (login under `your-exposed-keycloak-url/realms/loculusRealm/account/`)
 - and more testusers, for each browser in the e2e test following the pattern: `testuser_[processId]_[browser]` with password `testuser_[processId]_[browser]` 
 - These testusers will be added to the `testGroup` in the setup for e2e tests. If you change the number of browsers in the e2e test, you need to adapt `website/tests/playwrightSetup.ts` accordingly. 
 
+### Group management
+
+ - Groups are entities managed by the backend, uniquely identified by a name.
+ - Sequence entries are owned by a group, any modification to a sequence entry must be authorized by a member of the group.
+ - Each user can be a member of multiple groups.
+ - Users can create new groups, becoming the initial member automatically.
+ - Group members have the authority to add or remove other members.
+ - If the last user leaves a group, the group becomes 'dangling'—it exists but is no longer accessible, and a new group with the same name cannot be created.
+ - Admin users can manually delete a group directly on the DB but must transfer ownership of sequence entries to another group before doing so to fulfill the foreign key constraint.
+
+ For testing we added all users declared above to the group `testGroup`. 
+
+
 ## Contributing to Loculus
 
 Contributions are very welcome!

backend/docs/runtime_view.md

@@ -5,15 +5,15 @@
 Extension from [docs/glossary.md](../../docs/glossary.md)
 
 - Unpreprocessed data: the data that the submitter provides
-- Preprocessed data: the data that the preprocessing pipeline provides/derives based on the unpreprocesed data
+- Preprocessed data: the data that the preprocessing pipeline provides/derives based on the unpreprocessed data
 - Revision: a new version of unpreprocessed data associated with an existing accession that is already released
 - Revocation: a new version that is associated with an existing accession that is already released and that is marked as revocation. Data are empty.
 
 ## Initial submission
 
-To submit new sequences, the user calls the `/submit` endpoint and sends unpreprocessed data. 
+To submit new sequences, the user (on behalf of a group) calls the `/submit` endpoint and sends unpreprocessed data. 
 Data may be compressed using zstd, gzip, bzip2, xz, lzma or zip.
-For each sequence, Loculus creates a new row in the "sequenceEntries" table.
+For each sequence, a new row in the "sequenceEntries" table is created.
 It generates a new accession. The version number of the sequence entries is 1.
 
 ### Preprocessing & Editing
@@ -48,19 +48,19 @@ The following diagram shows the different statuses and their transitions. The **
 
 ## Revision
 
-To revise a sequence entery that has been released (i.e., the status is APPROVED_FOR_RELEASE),
+To revise a sequence entry that has been released (i.e., the status is APPROVED_FOR_RELEASE),
 the user calls the `/revise` endpoint and sends accessions and unpreprocessed data.
-For each revised sequence entery, Loculus creates a new row in the "sequencEntries" table.
+For each revised sequence entry, the user has to be part of the group for which the entry was initially submitted. Then a new row in the "sequenceEntries" table is created.
 It does not change any existing rows and does not create new accessions.
 The new rows have an incremented version number.
 
 The new entry will be treated the same way as a new submission and undergoes the same status transitions (see diagram in the "Initial submission" section).
 
 ## Revocation
 
-To revoke a sequence entery that has been released (i.e., the status is APPROVED_FOR_RELEASE),
+To revoke a sequence entry that has been released (i.e., the status is APPROVED_FOR_RELEASE),
 the user calls the `/revoke` endpoint and sends accessions.
-For each revoked sequence entry, Loculus creates a new row in the "sequenceEntris" table.
+For each revoked sequence entry, the user has to be part of the group for which the entry was initially submitted. Then a new row in the "sequenceEntries" table is created.
 The unpreprocessed data are empty. The "revoked" flag is set to true.
 The new rows have an incremented version number  (see diagram in the "Initial submission" section).
 

backend/src/main/kotlin/org/loculus/backend/controller/SubmissionController.kt

@@ -57,7 +57,7 @@ class SubmissionController(
     private val iteratorStreamer: IteratorStreamer,
 ) {
 
-    @Operation(description = "Submit data for new sequence entries as multipart/form-data")
+    @Operation(description = SUBMIT_DESCRIPTION)
     @ApiResponse(responseCode = "200", description = SUBMIT_RESPONSE_DESCRIPTION)
     @PostMapping("/submit", consumes = ["multipart/form-data"])
     fun submit(

backend/src/main/kotlin/org/loculus/backend/controller/SubmissionControllerDescriptions.kt

@@ -107,12 +107,20 @@ provided dataset. It is used to associate metadata to the sequences in the seque
 Additionally, the column 'accession' is required and must match the accession of the original sequence entry.
 """
 
+const val SUBMIT_DESCRIPTION = """
+Submit new data as multipart/form-data.
+The user submits data on behalf of a group that they must be a member of.
+"""
+
 const val REVISE_DESCRIPTION = """
-Submit revised data for new accession versions as multipart/form-data.
-If any of the given sequence entries do not exist (identified by the column 'accession' in the metadata file),
- or the user has no right to revise any of the sequence entries, or the last accession version is not in status 
- 'APPROVED_FOR_RELEASE',  i.e. not revisable, or if the provided files contain unspecified content, this will return an error and 
- roll back the whole transaction.
+Submit revised data for new accession versions as multipart/form-data. The following rules apply:
+ - Given sequence entries must exist (identified by the column 'accession' in the metadata file) 
+ - The user has the right to revise all of the sequence entries (the user is part of the group for that a sequence 
+entry was initially submitted)
+ - The last accession version is in status  'APPROVED_FOR_RELEASE', i.e. revisable
+ - The provided files contain only specified content
+ 
+If any of above does not apply, this will return an error and roll back the whole transaction.
 """
 
 const val DELETE_SEQUENCES_DESCRIPTION = """