feat(backend): add backend API support for generalized collections

backend/README.md

@@ -12,14 +12,40 @@ You have to provide config information to the backend:
 * Dashboards configuration, e.g. the LAPIS instances of the organisms.
   We have profiles available that only need to be activated via `spring.profiles.active`.
 * Database connection configuration: values need to be passed via [external properties](https://docs.spring.io/spring-boot/reference/features/external-config.html).
-  For local development, we have a `local-db` profile available. 
+  For local development, we have a `local-db` profile available.
   You can also check that for required properties.
 
+### Start local database
+
+Start the local PostgreSQL database using Docker Compose (from the repo root):
+
+```bash
+docker compose up -d database
+```
+
+Stop the database:
+
+```bash
+docker compose down database
+```
+
+Stop and remove data volumes:
+
+```bash
+docker compose down -v database
+```
+
+### Run the backend
+
 To run the backend locally, you can use the following command:
 ```bash
 ./gradlew bootRun --args='--spring.profiles.active=local-db,dashboards-prod'
 ```
 
+The backend will be available at:
+- Base URL: `http://localhost:8080`
+- Swagger UI: `http://localhost:8080/swagger-ui/index.html`
+
 Run tests:
 
 ```bash

backend/src/main/kotlin/org/genspectrum/dashboardsbackend/api/Collection.kt

@@ -0,0 +1,81 @@
+package org.genspectrum.dashboardsbackend.api
+
+import io.swagger.v3.oas.annotations.media.Schema
+
+@Schema(
+    description = "A collection of variants",
+    example = """
+{
+    "id": 1,
+    "name": "My Collection",
+    "ownedBy": "user123",
+    "organism": "covid",
+    "description": "A collection of interesting variants",
+    "variants": []
+}
+""",
+)
+data class Collection(
+    val id: Long,
+    val name: String,
+    val ownedBy: String,
+    val organism: String,
+    val description: String?,
+    val variants: List<Variant>,
+)
+
+@Schema(
+    description = "Request to create a collection",
+    example = """
+{
+    "name": "My Collection",
+    "organism": "covid",
+    "description": "A collection of interesting variants",
+    "variants": [
+        {
+            "type": "query",
+            "name": "BA.2 in USA",
+            "description": "BA.2 lineage cases in USA",
+            "countQuery": "country='USA' & lineage='BA.2'",
+            "coverageQuery": "country='USA'"
+        }
+    ]
+}
+""",
+)
+data class CollectionRequest(
+    val name: String,
+    val organism: String,
+    val description: String? = null,
+    val variants: List<VariantRequest>,
+)
+
+@Schema(
+    description = "Request to update a collection",
+    example = """
+{
+    "name": "Updated Collection Name",
+    "description": "Updated description",
+    "variants": [
+        {
+            "type": "query",
+            "id": 1,
+            "name": "BA.2 in USA",
+            "description": "BA.2 lineage cases in USA",
+            "countQuery": "country='USA' & lineage='BA.2'",
+            "coverageQuery": "country='USA'"
+        },
+        {
+            "type": "query",
+            "name": "New Variant Without ID",
+            "countQuery": "country='Germany'"
+        }
+    ]
+}
+""",
+)
+data class CollectionUpdate(
+    val name: String? = null,
+    val description: String? = null,
+    val variants: List<VariantUpdate>? = null,
+)

backend/src/main/kotlin/org/genspectrum/dashboardsbackend/api/MutationListDefinition.kt

@@ -0,0 +1,16 @@
+package org.genspectrum.dashboardsbackend.api
+
+import com.fasterxml.jackson.annotation.JsonInclude
+
+/**
+ * A JSON object with mutation lists (keys: aaMutations, nucMutations, ...)
+ * as well as lineage filtering under the "filters" key
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+data class MutationListDefinition(
+    val aaMutations: List<String>? = null,
+    val nucMutations: List<String>? = null,
+    val aaInsertions: List<String>? = null,
+    val nucInsertions: List<String>? = null,
+    val filters: Map<String, String>? = null,
+)

backend/src/main/kotlin/org/genspectrum/dashboardsbackend/api/Variant.kt

@@ -0,0 +1,222 @@
+package org.genspectrum.dashboardsbackend.api
+
+import com.fasterxml.jackson.annotation.JsonCreator
+import com.fasterxml.jackson.annotation.JsonProperty
+import com.fasterxml.jackson.annotation.JsonSubTypes
+import com.fasterxml.jackson.annotation.JsonTypeInfo
+import io.swagger.v3.oas.annotations.media.Schema
+import org.genspectrum.dashboardsbackend.api.Variant.MutationListVariant
+import org.genspectrum.dashboardsbackend.api.Variant.QueryVariant
+
+enum class QueryVariantType {
+    @JsonProperty("query")
+    QUERY,
+}
+
+enum class MutationListVariantType {
+    @JsonProperty("mutationList")
+    MUTATION_LIST,
+}
+
+@JsonTypeInfo(
+    use = JsonTypeInfo.Id.NAME,
+    include = JsonTypeInfo.As.PROPERTY,
+    property = "type",
+)
+@JsonSubTypes(
+    JsonSubTypes.Type(value = QueryVariant::class, name = "query"),
+    JsonSubTypes.Type(value = MutationListVariant::class, name = "mutationList"),
+)
+@Schema(
+    description = "Base interface for different variant types",
+)
+sealed interface Variant {
+    val id: Long
+    val collectionId: Long
+
+    @Schema(
+        description = "A variant defined by LAPIS queries",
+        example = """
+{
+    "type": "query",
+    "id": 1,
+    "collectionId": 2,
+    "name": "BA.2 in USA",
+    "description": "BA.2 lineage cases in USA",
+    "countQuery": "country='USA' & lineage='BA.2'",
+    "coverageQuery": "country='USA'"
+}
+""",
+    )
+    data class QueryVariant @JsonCreator constructor(
+        override val id: Long,
+        override val collectionId: Long,
+        val name: String,
+        val description: String?,
+        val countQuery: String,
+        val coverageQuery: String? = null,
+    ) : Variant {
+        val type: QueryVariantType = QueryVariantType.QUERY
+    }
+
+    @Schema(
+        description = "A variant defined by a list of mutations",
+        example = """
+{
+    "type": "mutationList",
+    "id": 1,
+    "collectionId": 2,
+    "name": "Omicron mutations",
+    "description": "Key mutations for Omicron",
+    "mutationList": {
+        "aaMutations": ["S:N501Y", "S:E484K", "S:K417N"]
+    }
+}
+""",
+    )
+    data class MutationListVariant @JsonCreator constructor(
+        override val id: Long,
+        override val collectionId: Long,
+        val name: String,
+        val description: String?,
+        val mutationList: MutationListDefinition,
+    ) : Variant {
+        val type: MutationListVariantType = MutationListVariantType.MUTATION_LIST
+    }
+}
+
+@JsonTypeInfo(
+    use = JsonTypeInfo.Id.NAME,
+    include = JsonTypeInfo.As.PROPERTY,
+    property = "type",
+)
+@JsonSubTypes(
+    JsonSubTypes.Type(value = VariantRequest.QueryVariantRequest::class, name = "query"),
+    JsonSubTypes.Type(value = VariantRequest.MutationListVariantRequest::class, name = "mutationList"),
+)
+@Schema(
+    description = "Request to create a variant",
+)
+sealed interface VariantRequest {
+    @Schema(
+        description = "Request to create a query variant",
+        example = """
+{
+    "type": "query",
+    "name": "BA.2 in USA",
+    "description": "BA.2 lineage cases in USA",
+    "countQuery": "country='USA' & lineage='BA.2'",
+    "coverageQuery": "country='USA'"
+}
+""",
+    )
+    data class QueryVariantRequest(
+        val name: String,
+        val description: String? = null,
+        val countQuery: String,
+        val coverageQuery: String? = null,
+    ) : VariantRequest {
+        val type: QueryVariantType = QueryVariantType.QUERY
+    }
+
+    @Schema(
+        description = "Request to create a mutation list variant",
+        example = """
+{
+    "type": "mutationList",
+    "name": "Omicron mutations",
+    "description": "Key mutations for Omicron",
+    "mutationList": {
+        "aaMutations": ["S:N501Y", "S:E484K", "S:K417N"]
+    }
+}
+""",
+    )
+    data class MutationListVariantRequest(
+        val name: String,
+        val description: String? = null,
+        val mutationList: MutationListDefinition,
+    ) : VariantRequest {
+        val type: MutationListVariantType = MutationListVariantType.MUTATION_LIST
+    }
+}
+
+@JsonTypeInfo(
+    use = JsonTypeInfo.Id.NAME,
+    include = JsonTypeInfo.As.PROPERTY,
+    property = "type",
+)
+@JsonSubTypes(
+    JsonSubTypes.Type(value = VariantUpdate.QueryVariantUpdate::class, name = "query"),
+    JsonSubTypes.Type(value = VariantUpdate.MutationListVariantUpdate::class, name = "mutationList"),
+)
+@Schema(
+    description = "Request to update or create a variant",
+)
+sealed interface VariantUpdate {
+    val id: Long?
+
+    @Schema(
+        description = "Request to update or create a query variant",
+        example = """
+{
+    "type": "query",
+    "id": 1,
+    "name": "BA.2 in USA",
+    "description": "BA.2 lineage cases in USA",
+    "countQuery": "country='USA' & lineage='BA.2'",
+    "coverageQuery": "country='USA'"
+}
+""",
+    )
+    data class QueryVariantUpdate(
+        override val id: Long? = null,
+        val name: String,
+        val description: String? = null,
+        val countQuery: String,
+        val coverageQuery: String? = null,
+    ) : VariantUpdate {
+        val type: QueryVariantType = QueryVariantType.QUERY
+    }
+
+    @Schema(
+        description = "Request to update or create a mutation list variant",
+        example = """
+{
+    "type": "mutationList",
+    "id": 1,
+    "name": "Omicron mutations",
+    "description": "Key mutations for Omicron",
+    "mutationList": {
+        "aaMutations": ["S:N501Y", "S:E484K", "S:K417N"]
+    }
+}
+""",
+    )
+    data class MutationListVariantUpdate(
+        override val id: Long? = null,
+        val name: String,
+        val description: String? = null,
+        val mutationList: MutationListDefinition,
+    ) : VariantUpdate {
+        val type: MutationListVariantType = MutationListVariantType.MUTATION_LIST
+    }
+
+    fun toVariantRequest(): VariantRequest {
+        require(id == null) { "Cannot convert a VariantUpdate with an existing id to a VariantRequest: $id" }
+        return when (this) {
+            is QueryVariantUpdate -> VariantRequest.QueryVariantRequest(
+                name = name,
+                description = description,
+                countQuery = countQuery,
+                coverageQuery = coverageQuery,
+            )
+
+            is MutationListVariantUpdate -> VariantRequest.MutationListVariantRequest(
+                name = name,
+                description = description,
+                mutationList = mutationList,
+            )
+        }
+    }
+}

backend/src/main/kotlin/org/genspectrum/dashboardsbackend/config/BackendSpringConfig.kt

@@ -7,6 +7,7 @@ import org.flywaydb.core.Flyway
 import org.genspectrum.dashboardsbackend.logging.REQUEST_ID_HEADER
 import org.genspectrum.dashboardsbackend.logging.REQUEST_ID_HEADER_DESCRIPTION
 import org.jetbrains.exposed.spring.autoconfigure.ExposedAutoConfiguration
+import org.jetbrains.exposed.sql.Database
 import org.springdoc.core.customizers.OperationCustomizer
 import org.springframework.boot.autoconfigure.ImportAutoConfiguration
 import org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration
@@ -31,6 +32,10 @@ class BackendSpringConfig {
             .validateMigrationNaming(true)
         val flyway = Flyway(configuration)
         flyway.migrate()
+
+        // Set up exposed database connection after migration is done
+        Database.connect(dataSource)
+
         return flyway
     }