refactor: migrate live quiz to unified data structure (i.e., from question instances/blocks to element block and element instances)

.github/workflows/cypress-testing.yml

@@ -132,7 +132,7 @@ jobs:
 
       - name: Cypress run
         uses: cypress-io/github-action@v6
-        timeout-minutes: 20
+        timeout-minutes: 60
         with:
           install: false
           wait-on: 'http://127.0.0.1:3000/api/graphql, http://127.0.0.1:3001, http://127.0.0.1:3002, http://127.0.0.1:3003, http://127.0.0.1:3010'

.github/workflows/test-graphql.yml

@@ -27,5 +27,13 @@ jobs:
       - name: Test functions
         shell: bash
         run: |
-          cd packages/graphql
+          cd packages/prisma
+          pnpm run build
+          cd ../types
+          pnpm run build
+          cd ../util
+          pnpm run build
+          cd ../grading
+          pnpm run build
+          cd ../graphql
           pnpm run test

CHANGELOG.md

@@ -377,7 +377,7 @@ All notable changes to this project will be documented in this file. See [standa
 
 ### Bug Fixes
 
-* ensure that validation in quesiton edit modal works properly ([#4251](https://github.com/uzh-bf/klicker-uzh/issues/4251)) ([5e26453](https://github.com/uzh-bf/klicker-uzh/commit/5e2645381465ccfbf26dac17d2f36b380ef9e4bf))
+* ensure that validation in question edit modal works properly ([#4251](https://github.com/uzh-bf/klicker-uzh/issues/4251)) ([5e26453](https://github.com/uzh-bf/klicker-uzh/commit/5e2645381465ccfbf26dac17d2f36b380ef9e4bf))
 * require that the user specifies sample solutions for open questions when activated ([#4252](https://github.com/uzh-bf/klicker-uzh/issues/4252)) ([0c5aa6b](https://github.com/uzh-bf/klicker-uzh/commit/0c5aa6b1c15e00813f4485e9380d53728ca527c7))
 
 ## [3.2.0-alpha.20](https://github.com/uzh-bf/klicker-uzh/compare/v3.2.0-alpha.19...v3.2.0-alpha.20) (2024-09-06)

README.md

@@ -11,11 +11,11 @@
 KlickerUZH v3.0 uses multiple different web applications and services, which communicate with each other:
 
 - [Frontend PWA](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/frontend-pwa) is the student frontend of KlickerUZH, which contains the student views for live quizzes, microlearnings, practice quizzes, leaderboards and more.
-- [Frontend Manage](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/frontend-manage) is the lecturer frontend of KlickerUZH, which provides all the functionalities that lecturers need, including but not limited to question management, session management, course management and analytics.
-- [Fontend Control](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/frontend-control) is a minimal controller frontend, which allows to control live sessions from mobile devices in an optimized layout. Soon, this app will also be available as a [PowerPoint integration](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/office-addin) (work in progress) for catalyst users.
+- [Frontend Manage](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/frontend-manage) is the lecturer frontend of KlickerUZH, which provides all the functionalities that lecturers need, including but not limited to question management, activity management, course management and analytics.
+- [Frontend Control](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/frontend-control) is a minimal controller frontend, which allows to control live quizzes from mobile devices in an optimized layout. Soon, this app will also be available as a [PowerPoint integration](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/office-addin) (work in progress) for catalyst users.
 - [Fontend Authentication](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/auth) is the authentication frontend of KlickerUZH, providing login functionalities through Edu-ID accounts and delegated logins to the manage frontend.
 - [Backend Docker](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/backend-docker) is the main backend service of KlickerUZH.
-- [Backend Responses](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/func-incoming-responses) is a service that handles incoming student responses during a live session and puts them into an Azure queue for improved load handling.
+- [Backend Responses](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/func-incoming-responses) is a service that handles incoming student responses during a live quizzes and puts them into an Azure queue for improved load handling.
 - [Backend Response Processor](https://github.com/uzh-bf/klicker-uzh/tree/v3/apps/func-response-processor) accesses queued elements from the aforementioned service and processes them by computing scores and experience points, updating the cache, etc.
 
 In addition to the key application components, this repository also includes the codebases for our landing page and documentation at [www.klicker.uzh.ch](https://www.klicker.uzh.ch/), as well as deployment scripts for Helm/Kubernetes. An updated deployment documentation for self-hosting KlickerUZH v3.0 will be added until the end of the year.

_down_macos.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+docker compose down postgres redis_exec redis_cache reverse_proxy_macos

apps/auth/package.json

@@ -8,7 +8,7 @@
     "@klicker-uzh/prisma": "workspace:*",
     "@klicker-uzh/shared-components": "workspace:*",
     "@next-auth/prisma-adapter": "1.0.7",
-    "@uzh-bf/design-system": "3.0.0-alpha.34",
+    "@uzh-bf/design-system": "3.0.0-alpha.35",
     "axios": "1.7.7",
     "bcryptjs": "2.4.3",
     "js-cookie": "3.0.5",
@@ -17,7 +17,6 @@
     "next": "15.0.0",
     "next-auth": "4.24.8",
     "next-intl": "3.21.1",
-    "nookies": "2.5.2",
     "react": "18.3.1",
     "react-dom": "18.3.1",
     "sharp": "0.33.5",

apps/backend-docker/package.json

@@ -56,7 +56,7 @@
     "@types/passport": "^1.0.16",
     "@types/passport-jwt": "^4.0.1",
     "@types/ws": "^8.5.12",
-    "@uzh-bf/design-system": "3.0.0-alpha.34",
+    "@uzh-bf/design-system": "3.0.0-alpha.35",
     "axios": "~1.7.7",
     "cross-env": "~7.0.3",
     "dotenv": "~16.4.5",

apps/backend-docker/scripts/2023-11-13_upgrade_question_data.ts

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 import type { PrismaMigrationClient } from '@klicker-uzh/graphql/src/types/app.js'
 // import { PrismaClient } from '@klicker-uzh/prisma'
 

apps/backend-docker/scripts/checkRedisConsistency.ts

@@ -1,4 +1,4 @@
-import { PrismaClient } from '@klicker-uzh/prisma'
+import { PrismaClient, PublicationStatus } from '@klicker-uzh/prisma'
 import { Redis } from 'ioredis'
 
 async function run() {
@@ -12,18 +12,18 @@ async function run() {
     tls: process.env.REDIS_TLS ? {} : undefined,
   })
 
-  const sessions = await prisma.liveSession.findMany({
+  const quizzes = await prisma.liveQuiz.findMany({
     where: {
       status: {
-        not: 'RUNNING',
+        not: PublicationStatus.PUBLISHED,
       },
     },
   })
 
   let count = 0
 
-  for (const session of sessions) {
-    const invalidKeys = await redisExec.keys(`s:${session.id}:*`)
+  for (const quiz of quizzes) {
+    const invalidKeys = await redisExec.keys(`lq:${quiz.id}:*`)
 
     if (invalidKeys.length > 0) {
       count += invalidKeys.length

apps/backend-docker/scripts/fixPointsInconsistency.ts

@@ -12,17 +12,17 @@ const redisExec = new Redis({
   tls: process.env.REDIS_TLS ? {} : undefined,
 })
 
-// deduct points from course leaderboard entries: 1x points in sessionLB
+// deduct points from course leaderboard entries: 1x points in quizLB
 const FAILURES = 1
 
 const COURSE_ID = ''
-const SESSION_ID = ''
+const QUIZ_ID = ''
 
-const sessionLB = await redisExec.hgetall(`s:${SESSION_ID}:lb`)
-const sessionXP = await redisExec.hgetall(`s:${SESSION_ID}:xp`)
+const quizLB = await redisExec.hgetall(`lq:${QUIZ_ID}:lb`)
+const quizXP = await redisExec.hgetall(`lq:${QUIZ_ID}:xp`)
 
 const results = await Promise.allSettled(
-  Object.entries(sessionLB).map(async ([participantId, score]) => {
+  Object.entries(quizLB).map(async ([participantId, score]) => {
     const lbEntry = await prisma.leaderboardEntry.findFirst({
       where: {
         participantId,

apps/docs/docs/gamification/experience.mdx

@@ -2,7 +2,7 @@
 title: XP and Levels
 ---
 
-While participants collect points for correct answers on a course level, experience points (XP) are collected across courses and allow students to level up. This represents an important part of our gamification concept, making sure that students keep making progress across different courses and activities. However, students are not only awarded experience points for answering questions correctly (in live settings as well as learning elements and micro sessions), but also when obtaining achievements, solving group challenges and many more activities.
+While participants collect points for correct answers on a course level, experience points (XP) are collected across courses and allow students to level up. This represents an important part of our gamification concept, making sure that students keep making progress across different courses and activities. However, students are not only awarded experience points for answering questions correctly (in live settings as well as practice quizzes and microlearnings), but also when obtaining achievements, solving group challenges and many more activities.
 
 As usual, levelling up will be faster in the beginning and then require a growing amount of additional points later on. KlickerUZH currently uses the following formula to compute the required amount of experience points for some level $i$ as $\text{XP}_{\text{req}}(i)$:
 

apps/docs/docs/gamification/grading_logic.mdx

@@ -4,7 +4,7 @@ title: Grading Logic
 
 In order to distribute points, XP and achievements based on the performance of the participants in various activities, an automated grading logic has been implemented in KlickerUZH. This chapter provides a detailed explanation of the approaches employed for different element and activity types, including practice quizzes, microlearnings and live quizzes.
 
-The presented grading approach assumes that all considered questions have a defined correct solution (or possibly multiple solutions), as this is required in asynchronous activities, except for free-text questions. During live sessions where questions without sample solutions were used, the participants are awarded a fixed amount of 10 points for taking part in each poll. Please also note that the [grading approach for live quizzes](#grading-in-live-quizzes) slightly extends the logic of asynchronous activities and that some element types are only available in select activities.
+The presented grading approach assumes that all considered questions have a defined correct solution (or possibly multiple solutions), as this is required in asynchronous activities, except for free-text questions. During live quizzes where questions without sample solutions were used, the participants are awarded a fixed amount of 10 points for taking part in each poll. Please also note that the [grading approach for live quizzes](#grading-in-live-quizzes) slightly extends the logic of asynchronous activities and that some element types are only available in select activities.
 
 ## Grading by Question Type
 
@@ -14,7 +14,7 @@ The grading logic will first be described on the example of practice quizzes and
 
 The point multipliers, which can be specified both on a question and activity level, are combined during the creation of the activity and applied to the total awarded points (including basic points and potential bonuses). If no multipliers were specified, this factor defaults to 1.
 
-Multipliers can be used to weigh questions according to their difficulty and reward participation in certain quizzes with more points (e.g. quiz on exam level during the last lecture of the semester vs. an introductory quiz in the first lecture). The same multiplier concept also applies to live sessions.
+Multipliers can be used to weigh questions according to their difficulty and reward participation in certain quizzes with more points (e.g. quiz on exam level during the last lecture of the semester vs. an introductory quiz in the first lecture). The same multiplier concept also applies to live quizzes.
 
 ### Grading Single Choice Questions
 
@@ -70,14 +70,14 @@ For free text questions, you can currently specify a selection of correct respon
 
 During synchronous live quizzes, every participant will receive 10 points for each submitted answer, independent of its correctness. If the submitted answer is correct, 5 additional points will be awarded. For partially correct answers, these 5 points are multiplied with a factor described in the sections above. If no sample solution is defined, students will not receive any time-dependent bonus, but only the fixed amount of 10 points (no multiplication with multiplier).
 
-To incentivize fast and correct answers during live sessions, additional bonus points are awarded. Starting time with the first correct answer, players will receive up to 45 points (default setting), depending on the time that passed between the first correct answer and theirs. By default, the slope to zero points is implemented with a duration of 20 seconds.
+To incentivize fast and correct answers during live quizzes, additional bonus points are awarded. Starting time with the first correct answer, players will receive up to 45 points (default setting), depending on the time that passed between the first correct answer and theirs. By default, the slope to zero points is implemented with a duration of 20 seconds.
 
-The corresponding resulting point curves for correct and wrong answers during live sessions, when starting time with the first correct response, are shown in the plot below (not considering multipliers).
+The corresponding resulting point curves for correct and wrong answers during live quizzes, when starting time with the first correct response, are shown in the plot below (not considering multipliers).
 
 <div align="center">
   <img
     style={{ width: 600 }}
-    alt="Illustration of Grading in Live Sessions"
+    alt="Illustration of Grading in Live Quizzes"
     src="/img_v3/21_live_quiz_awarded_points.svg"
   />
 </div>

apps/docs/docs/tutorials/course_management.mdx

@@ -87,6 +87,6 @@ This process helps ensure that groups are formed **fairly and efficiently**. The
    1. Participants that are **alone** in a group are automatically added to the random assignment pool, while their group is resolved.
    2. Students remaining in the assignment pool are evenly distributed into **new groups** to match the preferred group size.
 
-5. **Manual group creation** during the creation period: Lecturers can manually finalize group assignments at any time through the course's **group overview page** (ahead of the group formation deadline). This allows you to use randomized group formation in a single in-class session instead of across a longer timespan. To do so, you can select the "**Assign random groups**" button within the group overview on the course page (screenshot below). This will close group creation and distribute students from the pool into existing groups as described in the previous step. To reopen group formation after manual finalization, lecturers can **extend the deadline** in the course settings.
+5. **Manual group creation** during the creation period: Lecturers can manually finalize group assignments at any time through the course's **group overview page** (ahead of the group formation deadline). This allows you to use randomized group formation in a single in-class quizzes instead of across a longer timespan. To do so, you can select the "**Assign random groups**" button within the group overview on the course page (screenshot below). This will close group creation and distribute students from the pool into existing groups as described in the previous step. To reopen group formation after manual finalization, lecturers can **extend the deadline** in the course settings.
 
 ![Random Group Creation - Lecturer View](/img_v3/18_random_groups_lecturer.png)

apps/docs/docs/tutorials/element_management.mdx

@@ -96,5 +96,5 @@ Elements (questions, flashcards, and content elements) are the building blocks o
 - **Delete**: Remove unwanted elements (note: this action is irreversible)
 
 :::info
-Most elements can be used in any learning activity, with some restrictions. For detailed information on embedding elements into different activities, refer to the following sections. Remember, elements are persistent within existing sessions, even if deleted from your element pool.
+Most elements can be used in any learning activity, with some restrictions. For detailed information on embedding elements into different activities, refer to the following sections. Remember, elements are persistent within existing quizzes, even if deleted from your element pool.
 :::

apps/docs/docs/tutorials/group_activity.mdx

@@ -35,7 +35,7 @@ To create a group activity, navigate to the question pool and use the button at
 
 In a first step, you will be asked to provide general information about the group activity. The following fields are available for customization:
 
-- **Name**: The name of the group activity allows the user to distinguish the particular session from others. It is therefore only visible to the users themselves.
+- **Name**: The name of the group activity allows the user to distinguish the particular activity from others. It is therefore only visible to the users themselves.
 - **Display Name**: This name will be shown to the participants while the group activity is being performed.
 - **Description**: A description of the group activity can optionally be added and will be displayed to the participants as an introduction to the group activity. While not required, we highly recommend to provide general information about the group activity here.
 

apps/docs/docs/tutorials/live_qa.mdx

@@ -24,7 +24,7 @@ Live Quizzes in KlickerUZH can be coupled with a Live Q&A that enables students
   title="KlickerUZH - Live Q&A"
 ></iframe>
 
-A Live Q&A is embedded in the Live Quiz and can be activated during a Live Quiz session. For more details on the Live Quiz, review the dedicated [tutorial on live quiz creation](/tutorials/live_quiz/).
+A Live Q&A is embedded in the Live Quiz and can be activated during its execution. For more details on the Live Quiz, review the dedicated [tutorial on live quiz creation](/tutorials/live_quiz/).
 
 1. Activate Live Q&A: As soon as you activate a question block (displayed in green), the Live Q&A can be activated.
 2. Manage questions: By clicking on the eye symbol, you can make the question visible for all the participants. The question can then not only be seen by others, but also be upvoted. Furthermore, you can sort the incoming questions or delete them.