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

[fhennig]

resolves #1045

Summary

Adds collections:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Variant Collection",
  "ownedBy": "user123",
  "organism": "covid",
  "description": "A collection tracking important SARS-CoV-2 variants",
  "variants": [
    {
      "type": "query",
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "collectionId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "BA.2 in USA",
      "description": "BA.2 lineage cases in the United States",
      "countQuery": "country='USA' & lineage='BA.2'",
      "coverageQuery": "country='USA'"
    },
    {
      "type": "mutationList",
      "id": "660e8400-e29b-41d4-a716-446655440002",
      "collectionId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Omicron Key Mutations",
      "description": "Important spike protein mutations for Omicron",
      "mutationList": {
        "aaMutations": ["S:N501Y", "S:E484K", "S:K417N"]
      }
    }
  ]
}

A collection has a name and description and a list of variants. A variant is either defined as a lineage and a set of mutations, or as a query (just a string).

A collection has an owner and only the owner can modify or delete a collection. All collections are public.

New endpoints

• GET /collections - List collections with optional filtering by userId and organism
• GET /collections/{id} - Get a single collection with all its variants
• POST /collections - Create a new collection with variants
• PUT /collections/{id} - Update a collection (partial updates supported)
• DELETE /collections/{id} - Delete a collection (owner-only)

For the updating of collections: Name, description and variants can be updated independently, only the one you want to update needs to be supplied. For the variant list though, for each variant if you want to update one property, all other properties must also be given. This is where I think maybe we can change stuff later. It is easiest to do it like this though, also if you want to maybe remove the optional coverage query, its easy to implement like this.

Variants

A variant is either defined as a count (and optional coverage) query or as a list of mutations; the format is copied from how it is done in CovSpectrum:

{
    "nextcladePangoLineage": "BA.2",
    "aaMutations": [
      "S:N501Y",
      "ORF1a:P3395H",
      "ORF1b:P314L",
    ],
    "nucMutations": [
      "C241T",
      "C3037T",
      "A23063T"
    ],
    "aaInsertions": [
      "S:214:EPE",
    ],
    "nucInsertions": [],
  }

Other changes

I've added a new Docker Compose file to spin up a dev database.

PR Checklist

• All necessary documentation has been adapted.
• The implemented feature is covered by an appropriate test.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
dashboards	Ready	Preview, Comment	Mar 12, 2026 8:25am