### Setting Up KlickerUZH Development Environment

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet provides essential commands to initialize the KlickerUZH development environment. It covers installing project dependencies, starting the full development stack with Doppler environment variables, and preparing production-like components such as the database, Redis, and reverse proxy.

```bash
# Install dependencies
pnpm install

# Start development environment with Doppler environment variables
pnpm dev

# Start database, Redis, and reverse proxy only
pnpm run dev:prepare-prod
```

--------------------------------

### Project Setup Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/README.md

Essential commands for setting up the KlickerUZH Analytics project, covering dependency installation using Poetry and PNPM, Prisma schema synchronization, and explicit Python environment configuration.

```Shell
poetry install
```

```Shell
pnpm install
```

```Shell
util/sync-schema.sh
```

```Shell
poetry env use /Users/.../bin/python
```

--------------------------------

### Common Development Commands for Docusaurus

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/docs/CLAUDE.md

These commands are used to manage the KlickerUZH documentation application, including installing dependencies, starting the development server, building for production, deploying, and serving the built site locally.

```bash
# Install dependencies
pnpm install

# Start development server
pnpm start

# Build for production
pnpm build

# Deploy the docs site
pnpm deploy

# Serve the built site locally
pnpm serve
```

--------------------------------

### Frontend Management Application Development Commands (pnpm)

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

This snippet provides a list of common 'pnpm' commands used for developing the KlickerUZH frontend-manage application. It covers essential operations such as installing dependencies, starting the development server (with an option for Doppler environment variables), building for production, performing type checks, linting, and starting the production server. These commands are fundamental for setting up and managing the development environment.

```bash
# Install dependencies
pnpm install

# Start development server
pnpm dev

# Start with Doppler environment variables
pnpm dev:doppler

# Build for production
pnpm build

# Type checking
pnpm check

# Linting
pnpm lint

# Start production server
pnpm start
```

--------------------------------

### Development Workflow: Building and Running the Shared Components Package

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/shared-components/CLAUDE.md

These commands outline the standard development workflow for the `shared-components` package. They cover installing project dependencies, starting a local development server with live CSS reloading, building the package for production, and performing type-checking. These steps are essential for local development and deployment preparation.

```bash
# Install dependencies (from project root)
pnpm install

# Start development with live CSS reloading
pnpm run dev

# Build the package
pnpm run build

# Type-check the package
pnpm run check
```

--------------------------------

### Cypress Local Testing Environment Setup

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/cypress/CLAUDE.md

This snippet provides command-line instructions for setting up and running Cypress tests locally. It covers installing project dependencies, opening the Cypress test runner for interactive development, and executing tests headlessly for continuous integration or batch runs.

```bash
# Install dependencies
cd cypress
pnpm install

# Open Cypress test runner
pnpm cypress open

# Run tests headlessly
pnpm cypress run
```

--------------------------------

### TypeScript JSDoc Function Documentation Example

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

An example demonstrating the required JSDoc comment structure for TypeScript functions, including descriptions for parameters and return values, ensuring clear API documentation.

```typescript
/**
 * Brief summary.
 *
 * @param param1 - Description.
 * @returns Description.
 */

function example(param1: string): number {
  // implementation
}
```

--------------------------------

### Cypress User Workflow Test Example

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/cypress/CLAUDE.md

This snippet demonstrates a typical Cypress test structure for a user workflow. It includes setup and cleanup using `before` and `after` hooks, data loading from fixtures with `beforeEach`, user login, performing actions, and asserting results using `data-cy` attributes and fixture data.

```typescript
describe('User workflow', () => {
  before(() => cy.seed())
  after(() => cy.cleanup())

  beforeEach(function () {
    cy.fixture('fixture-name.json').then((data) => {
      this.data = data
    })
  })

  it('completes a workflow successfully', function () {
    // Login
    cy.loginLecturer()

    // Perform actions
    cy.get('[data-cy="element"]').click()

    // Assert results
    cy.get('[data-cy="result"]').should('contain', this.data.expectedValue)
  })
})
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/office-addin/README.md

Installs all necessary Node.js packages for the KlickerUZH PowerPoint add-in. This command should be executed after cloning the repository to set up the project environment.

```sh
npm install
```

--------------------------------

### Python Function Docstring Example (Google Style)

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet demonstrates the recommended Google style for writing docstrings in Python functions. It includes sections for a brief summary, arguments (Args), and return types (Returns), ensuring clear and consistent documentation for functions.

```Python
def example():
"""
Brief summary.

Args:
param1 (type): Description.

Returns:
type: Description.
"""
```

--------------------------------

### Common Task: Implementing a New Feature

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Comprehensive guide for implementing a new feature, from planning component hierarchy and state management to GraphQL operations, UI development, custom hooks, validation, error handling, and cross-device testing.

```APIDOC
1. Plan the component hierarchy and state management approach
2. Create necessary GraphQL operations in the graphql package
3. Implement UI components in the appropriate directories
4. Create custom hooks for complex logic or data fetching
5. Add form validation if needed
6. Implement error handling and loading states
7. Test across different devices and scenarios
```

--------------------------------

### Common Task: Adding a New Component

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Step-by-step guide for creating and integrating a new React component into the project, including prop typing, state management, internationalization, styling, and usage.

```APIDOC
1. Create a new component file in the appropriate feature directory
2. Define TypeScript interface for props
3. Implement the component with proper hooks and state management
4. Add internationalization using the messages from `@klicker-uzh/i18n`
5. Style using Tailwind classes
6. Import and use in parent components
```

--------------------------------

### Common Task: Creating a New Page

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Instructions for adding a new page to the Next.js application, covering file structure, component imports, data fetching with Apollo Client or SWR, layout setup, and authentication/permissions.

```APIDOC
1. Add a new file in the `/src/pages/` directory following Next.js routing
2. Import necessary components and hooks
3. Implement data fetching using Apollo Client or SWR
4. Set up proper layouts and page structure
5. Handle authentication and permissions appropriately
```

--------------------------------

### Start Development Server and Sideload Add-ins

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/office-addin/README.md

Initiates the development server and automatically sideloads both KlickerUZH add-ins into PowerPoint. This command enables live development with auto-reloading of source code changes.

```sh
npm run dev
```

--------------------------------

### Building KlickerUZH for Production

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet contains commands for building the KlickerUZH project. It includes commands to build all packages and applications for a production release, as well as a specific command for building them for testing purposes, ensuring different build configurations are supported.

```bash
# Build all packages and applications
pnpm build

# Build packages and applications for testing
pnpm build:test
```

--------------------------------

### TypeScript Examples for KlickerUZH Element Data Processing

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/util/CLAUDE.md

These TypeScript examples illustrate the usage of core functions for handling and transforming element data within the KlickerUZH platform. They demonstrate how to convert raw database element objects into a frontend-ready format, and how to initialize data structures for new element instance results and statistics tracking, ensuring consistent data handling across the application.

```typescript
// Transform a database element into frontend-ready data
const elementData = processElementData(element)

// Get initial results structure for a new element instance
const results = getInitialInstanceResults(elementData)

// Get initial statistics for a new element instance
const statistics = getInitialInstanceStatistics(instanceType)
```

--------------------------------

### Embed Microlearning Preparation Video

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/docs/docs/tutorials/microlearning.mdx

This HTML snippet embeds a video tutorial from UZH MediaSpace, guiding users through the process of preparing a microlearning activity. It specifies the video source, dimensions, and various permissions for playback and interaction within the embedded frame.

```HTML
<iframe
  id="kmsembed-0_wd8q4cfm"
  width="100%"
  height="400"
  src="https://uzh.mediaspace.cast.switch.ch/embed/secure/iframe/entryId/0_wd8q4cfm/uiConfId/23448425/st/0"
  class="kmsembed"
  allowfullscreen
  webkitallowfullscreen
  mozAllowFullScreen
  allow="autoplay *; fullscreen *; encrypted-media *"
  referrerPolicy="no-referrer-when-downgrade"
  sandbox="allow-downloads allow-forms allow-same-origin allow-scripts allow-top-navigation allow-pointer-lock allow-popups allow-modals allow-orientation-lock allow-popups-to-escape-sandbox allow-presentation allow-top-navigation-by-user-activation"
  frameborder="0"
  title="KlickerUZH - Prepare Microlearning"
></iframe>
```

--------------------------------

### Client-Side Response Validation Example

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/shared-components/CLAUDE.md

Shows how to use a utility function for validating user responses based on the question type, typically used within component logic.

```tsx
import { validateResponse } from '../utils/validateResponse'

// In component
const isValid = validateResponse(response, questionType)
```

--------------------------------

### Managing KlickerUZH Database with Prisma

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet outlines commands for managing the KlickerUZH database using Prisma. It includes syncing the Prisma schema between packages, deploying schema changes to the database, browsing data with Prisma Studio, and creating new database migration files.

```bash
# Sync Prisma schema between packages/prisma and apps/analytics
./util/sync-schema.sh

# Deploy Prisma schema changes to the database
pnpm run prisma:deploy

# Run Prisma Studio to browse data
pnpm run prisma:studio

# Create a new Prisma migration
pnpm run prisma:migrate
```

--------------------------------

### Execute Database Schema Migration and Sync Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

These commands are used to update the database schema after modifications to Prisma schema files. `pnpm run prisma:migrate` creates a new migration, and `./util/sync-schema.sh` synchronizes the schema across different packages.

```Shell
pnpm run prisma:migrate
```

```Shell
./util/sync-schema.sh
```

--------------------------------

### Python Environment Setup and Module Imports

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/aggregated_analytics.ipynb

This code block sets up the Python environment by modifying the system path to allow module imports from a parent directory and imports all necessary libraries for database interaction, date manipulation, and the core analytics computation function.

```python
import os
import json
from datetime import datetime
from prisma import Prisma
import pandas as pd

# set the python path correctly for module imports to work
import sys

sys.path.append("../../")

from src.modules.aggregated_analytics.compute_aggregated_analytics import (
    compute_aggregated_analytics,
)
```

--------------------------------

### TypeScript Examples for Recomputing Derived Permissions

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/util/CLAUDE.md

These TypeScript code snippets demonstrate how to invoke the utility functions responsible for recomputing derived permissions within the KlickerUZH system. The examples show how to trigger a recomputation for a specific object (e.g., an element) or for a particular user's permissions on an element, typically after changes to direct permissions or object relationships. The `prisma` client is passed as a dependency for database operations.

```typescript
// Recompute permissions for a specific object
await recomputeDerivedPermissions({ elementId: 123 }, prisma)

// Recompute permissions for a specific user on an object
await recomputeElementPermissionsUser({ id: 123, userId: 'user-id' }, prisma)
```

--------------------------------

### Managing KlickerUZH Releases

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet details commands for managing releases of the KlickerUZH project. It includes commands for creating standard releases, as well as specific commands for alpha, beta, and release candidate versions, facilitating a structured release process.

```bash
# Create a new release
pnpm release

# Create an alpha release
pnpm release:alpha

# Create a beta release
pnpm release:beta

# Create a release candidate
pnpm release:rc
```

--------------------------------

### Configuring NextIntlClientProvider for i18n in Next.js

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/i18n/CLAUDE.md

Shows the setup of `NextIntlClientProvider` in a Next.js application, integrating i18n messages, locale, and custom error handling functions for robust internationalization.

```typescript
<NextIntlClientProvider
  timeZone="Europe/Zurich"
  messages={pageProps.messages}
  locale={locale}
  onError={onError}
  getMessageFallback={getMessageFallback}
>
  {/* Application content */}
</NextIntlClientProvider>
```

--------------------------------

### Implement Transactional Service Function

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/graphql/CLAUDE.md

Example of an asynchronous service function demonstrating how to use a `PrismaTransactionContext` to ensure database operations are part of an atomic transaction. Operations performed via `ctx.prisma` will automatically be included in the transaction provided by the context.

```typescript
export async function createObject(
  args: CreateObjectArgs,
  ctx: PrismaTransactionContext
): Promise<Object> {
  // Operations will be part of the transaction from the context
  return await ctx.prisma.object.create({
    data: {...},
  })
}
```

--------------------------------

### Running KlickerUZH Tests

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This snippet provides commands for executing tests within the KlickerUZH project. It covers running all tests, running tests in watch mode for continuous feedback during development, and specifically opening the Cypress E2E test runner for end-to-end testing.

```bash
# Run all tests
pnpm test:run

# Run tests with watch mode
pnpm test:watch

# Run Cypress E2E tests
cd cypress && pnpm cypress open
```

--------------------------------

### Basic Markdown String Rendering

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/markdown/CLAUDE.md

A simple example demonstrating the fundamental usage of the `Markdown` component. It takes a `markdownString` variable as its `content` prop, rendering the provided markdown directly into React components. This is the most straightforward way to integrate markdown content.

```tsx
<Markdown content={markdownString} />
```

--------------------------------

### Extend Next.js Configuration with Custom Image Domains

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/next-config/CLAUDE.md

Example of how to add custom image domains to the Next.js configuration while preserving the base image settings provided by `getNextBaseConfig`. It demonstrates spreading existing image domains and appending new ones to the `domains` array.

```javascript
let nextConfig = {
  ...getNextBaseConfig({ BLOB_STORAGE_ACCOUNT_URL }),
  images: {
    ...getNextBaseConfig({ BLOB_STORAGE_ACCOUNT_URL }).images,
    domains: [
      ...getNextBaseConfig({ BLOB_STORAGE_ACCOUNT_URL }).images.domains,
      'custom-domain.com',
    ],
  },
}
```

--------------------------------

### PNPM Service Management Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/README.md

A list of commands executable via PNPM to manage the KlickerUZH Analytics service. These commands facilitate Prisma client generation, running the main analytics service, and starting the service in development watch mode.

```Shell
pnpm generate
```

```Shell
pnpm main
```

```Shell
pnpm dev
```

--------------------------------

### Documenting JSON Fields in Prisma Models

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/prisma/CLAUDE.md

This example illustrates the recommended practice for documenting JSON fields within Prisma models using JSDoc-style comments. This improves code readability and maintainability, especially for complex object structures, by providing inline documentation.

```TypeScript
/// [PrismaElementOptions]
```

--------------------------------

### Implement Object Activity Change Tracking System

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

This section describes the `object-changelog` branch's implementation of a change tracking system for application objects. It details the `ActivityLogEntry` model, its types (MESSAGE, MODIFICATION), polymorphic relations, and associated GraphQL operations for logging and retrieving changes.

```APIDOC
ActivityLogEntry Model:
  - Types: MESSAGE, MODIFICATION
  - Relations: Polymorphic relations to elements, courses, quizzes, and other object types
  - Properties: message_content (string), user (string), timestamp (datetime)

GraphQL Operations:
  - Retrieve activity log entries
  - Add activity log entries
```

--------------------------------

### Cypress Component Functionality Test Example

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/cypress/CLAUDE.md

This snippet illustrates a Cypress test focused on specific component functionality. It sets up the test environment by seeding data and navigating to a specific page, then performs actions on a component and asserts its existence. This structure is suitable for isolated component testing.

```typescript
describe('Component functionality', () => {
  before(() => cy.seed())
  after(() => cy.cleanup())

  beforeEach(() => {
    cy.loginLecturer()
    cy.visit('/specific-page')
  })

  it('performs specific function', () => {
    // Test specific functionality
    cy.get('[data-cy="component"]').click()
    cy.get('[data-cy="result"]').should('exist')
  })
})
```

--------------------------------

### Implement GraphQL Error Handling Pattern

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/graphql/CLAUDE.md

Example of a service function demonstrating a common error handling pattern for GraphQL operations. It includes initial validation checks, a try-catch block for the main operation logic, robust error logging, and translation of specific Prisma client errors (e.g., unique constraint violations) into more generic, user-friendly `GraphQLError` instances.

```typescript
export async function exampleOperation(args, ctx) {
  // Validation checks
  if (!args.requiredField) {
    throw new GraphQLError('REQUIRED_FIELD_MISSING')
  }

  try {
    // Operation logic
  } catch (error) {
    // Error logging
    console.error('Failed to perform operation', error)

    // Error translation
    if (error instanceof Prisma.PrismaClientKnownRequestError) {
      if (error.code === 'P2002') {
        throw new GraphQLError('DUPLICATE_ENTRY')
      }
    }

    // Generic error
    throw new GraphQLError('OPERATION_FAILED')
  }
}
```

--------------------------------

### Initialize Python Environment and Import Modules

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/activity_progress.ipynb

This snippet sets up the Python environment by appending a parent directory to the system path, ensuring that custom modules can be imported. It then imports necessary libraries like `os`, `json`, `datetime`, `prisma`, `pandas`, `sys`, and several custom modules related to course analytics and activity progress.

```python
import os
import json
from datetime import datetime
from prisma import Prisma
import pandas as pd
import sys

# set the python path correctly for module imports to work
sys.path.append("../../")

from src.modules.participant_course_analytics.get_running_past_courses import (
    get_running_past_courses,
)
from src.modules.activity_progress.get_course_progress_activities import (
    get_course_progress_activities,
)
from src.modules.activity_progress.compute_progress_counts import (
    compute_progress_counts,
)
from src.modules.activity_progress.save_practice_quiz_progress import (
    save_practice_quiz_progress,
)
from src.modules.activity_progress.save_microlearning_progress import (
    save_microlearning_progress,
)
```

--------------------------------

### Common Prisma Development Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/prisma/CLAUDE.md

A comprehensive list of `pnpm` commands used for various development tasks related to the Prisma database, including building the package, creating and applying migrations, resetting the database, seeding data, and opening Prisma Studio.

```bash
# Build the package (generates Prisma client)
pnpm run build

# Create a new migration
pnpm run prisma:migrate

# Create a migration without applying it
pnpm run prisma:migrate:create

# Apply pending migrations
pnpm run prisma:deploy

# Reset database and apply all migrations
pnpm run prisma:reset

# Reset with confirmation bypass (for scripts)
pnpm run prisma:reset:yes

# Seed the database with test data
pnpm run seed

# Open Prisma Studio to browse/edit data
pnpm run prisma:studio

# Run a script with environment variables
pnpm run script src/scripts/your-script.ts

# Run database push (for development, skips migrations)
pnpm run prisma:push
```

--------------------------------

### Example: Using Tailwind-Merge with React Components

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/shared-components/CLAUDE.md

This snippet demonstrates how to use `tailwind-merge` within a React component to conditionally apply and merge Tailwind CSS classes. It ensures that default styles are correctly combined with any additional classes passed via props, preventing conflicts and maintaining styling consistency. The example shows a simple `Button` component.

```tsx
import { twMerge } from 'tailwind-merge'

function Button({ className, ...props }) {
  return (
    <button
      className={twMerge('rounded bg-blue-500 px-4 py-2 text-white', className)}
      {...props}
    />
  )
}
```

--------------------------------

### Project Testing Guidelines

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Guidelines for ensuring quality and responsiveness when implementing or modifying features within the project, covering typing, responsiveness, form handling, GraphQL integration, and state management.

```APIDOC
1. Ensure component props are properly typed
2. Test in different viewport sizes for responsive behavior
3. Validate form submission and error handling
4. Check integration with GraphQL operations
5. Verify state management and side effects
```

--------------------------------

### Establish Database Connection and Configure Script

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/activity_progress.ipynb

This code initializes the Prisma ORM client, sets the `DATABASE_URL` environment variable for PostgreSQL connection, and establishes a connection to the database. It also defines a `verbose` flag for script settings, which can be used for controlling output verbosity.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"

db.connect()

# Script settings
verbose = False
```

--------------------------------

### Initialize Python Environment and Import Modules

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/participant_course_analytics.ipynb

This snippet sets up the Python environment by adjusting the `sys.path` to ensure custom modules can be imported correctly. It then imports essential libraries such as `os`, `json`, `datetime`, `prisma`, and `pandas`, along with specific internal modules required for participant course analytics computations.

```python
import os
import json
from datetime import datetime
from prisma import Prisma
import pandas as pd

# set the python path correctly for module imports to work
import sys
sys.path.append("../../")

from src.modules.participant_course_analytics.get_running_past_courses import (
    get_running_past_courses,
)
from src.modules.participant_course_analytics.get_active_weeks import get_active_weeks
from src.modules.participant_course_analytics.compute_participant_activity import (
    compute_participant_activity,
)
from src.modules.participant_course_analytics.save_participant_course_analytics import (
    save_participant_course_analytics,
)
```

--------------------------------

### Establish Database Connection and Configure Script

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/participant_course_analytics.ipynb

This code block initializes a Prisma client instance and configures the database connection. It sets the `DATABASE_URL` environment variable to connect to a PostgreSQL database and then establishes the connection. Additionally, a `verbose` flag is set for controlling script output.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"

db.connect()

# Script settings
verbose = False
```

--------------------------------

### TypeScript Interface for ActivityLogModificationDetails

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/prisma/CLAUDE.md

An example of a TypeScript interface definition, `ActivityLogModificationDetails`, which represents the structured type for a JSON field. These types are typically maintained in a separate types package and are referenced by the generated code.

```typescript
// Example ActivityLogModificationDetails type in types package
export interface ActivityLogModificationDetails {
  field: ActivityLogModificationFieldType | string
  oldValue: string
  newValue: string
}
```

--------------------------------

### Loading i18n Messages in Next.js `getStaticProps`

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/i18n/CLAUDE.md

Provides an example of asynchronously loading i18n messages for a specific locale within Next.js's `getStaticProps` function, making them available as page props.

```typescript
export async function getStaticProps({ locale }: GetStaticPropsContext) {
  return {
    props: {
      messages: (await import(`@klicker-uzh/i18n/messages/${locale}`)).default,
    },
  }
}
```

--------------------------------

### Initialize Python Environment and Import Modules

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/aggregated_course_analytics.ipynb

This snippet imports essential Python modules such as `os`, `json`, `datetime`, `pandas`, and the `Prisma` ORM client. It also sets up the Python system path to correctly import custom modules like `get_running_past_courses` and `compute_weekday_activity` from the project's source directory.

```python
import os
import json
from datetime import datetime
from prisma import Prisma
import pandas as pd

# set the python path correctly for module imports to work
import sys

sys.path.append("../../")

from src.modules.participant_course_analytics.get_running_past_courses import (
    get_running_past_courses,
)
from src.modules.aggregated_course_analytics.compute_weekday_activity import (
    compute_weekday_activity,
)
```

--------------------------------

### APIDOC: KlickerUZH Participant Entity

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

Documentation for the Participant entity in the KlickerUZH database schema. This entity represents students interacting with activities, outlining their properties and how they relate to courses and groups.

```APIDOC
Participant:
  description: Students who interact with activities
  properties:
    username: string
    email: string
    password: string
    avatar: string
    xp: number (experience points)
  relationships:
    Participation: can join courses
    ParticipantGroups: can belong to groups for activities
```

--------------------------------

### Get Next.js Base Configuration Function Signature

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/next-config/CLAUDE.md

Signature for the `getNextBaseConfig` function, which returns standard Next.js configuration. It accepts an object containing `BLOB_STORAGE_ACCOUNT_URL` for image storage and `NODE_ENV` to determine the environment mode.

```APIDOC
getNextBaseConfig({ BLOB_STORAGE_ACCOUNT_URL, NODE_ENV })
```

--------------------------------

### Establish Database Connection and Configure Settings

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/participant_performance.ipynb

Initializes the Prisma ORM client, sets the DATABASE_URL environment variable to connect to a PostgreSQL database, establishes the connection, and defines a script-specific setting for verbosity.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"

db.connect()

# Script settings
verbose = False
```

--------------------------------

### Get Next.js PWA Configuration Function Signature

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/next-config/CLAUDE.md

Signature for the `getNextPWAConfig` function, which returns Progressive Web App configuration options. It primarily uses `NODE_ENV` to control PWA behavior, such as disabling features in development.

```APIDOC
getNextPWAConfig({ NODE_ENV })
```

--------------------------------

### TypeScript i18n Message Structure Example

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/i18n/CLAUDE.md

Illustrates the hierarchical organization of translation keys within the i18n message files (e.g., `en.ts`, `de.ts`). Keys are grouped by feature area and component, facilitating structured localization.

```typescript
export default {
  shared: {
    // Common translations used across the application
    table: {
      download: 'Download as CSV',
      // ...
    },
    questions: {
      // Question-related translations
      // ...
    },
  },
  manage: {
    // Translations for the management interface
    courses: {
      // Course-related translations
      // ...
    },
    // ...
  },
  pwa: {
    // Translations for the progressive web app
    // ...
  },
  // ...
}
```

--------------------------------

### Development Workflow: Common CLI Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/backend-docker/CLAUDE.md

Essential command-line interface (CLI) commands for building, running, testing, and type-checking the application during development. These commands leverage pnpm for package management and streamline the development process.

```bash
# Build the application
pnpm build

# Start the development server
pnpm dev

# Run with test coverage
pnpm test

# Run type checking
pnpm check

# Start the application (after building)
pnpm start
```

--------------------------------

### Connect to Database and Configure Script Settings

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/aggregated_course_analytics.ipynb

This code block initializes the Prisma client for database operations. It sets the `DATABASE_URL` environment variable to establish a connection to a PostgreSQL database and then connects the Prisma client. A `verbose` flag is also set to control script output.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"
db.connect()

# Script settings
verbose = False
```

--------------------------------

### APIDOC: KlickerUZH User Entity

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/CLAUDE.md

Documentation for the User entity in the KlickerUZH database schema. This entity represents lecturers who create and manage questions and activities, detailing their properties and relationships within the system.

```APIDOC
User:
  description: Lecturers who create and manage questions and activities
  properties:
    shortname: string
    email: string
    catalystIndividual/Institutional: boolean (subscription status)
    locale: string (en/de)
  relationships:
    UserLogins: for authentication
```

--------------------------------

### Project Best Practices

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

A set of recommended best practices for development within the project, emphasizing component design, code organization, TypeScript usage, error handling, internationalization, permissions, styling, and responsiveness.

```APIDOC
1. Follow established component patterns in the codebase
2. Keep components focused and maintainable (under 300 lines)
3. Extract complex logic into custom hooks
4. Use TypeScript interfaces for all props and state
5. Implement proper error boundaries and fallbacks
6. Add descriptive comments for complex logic
7. Use the i18n system for all user-facing strings
8. Follow the established permission checking patterns
9. Maintain consistent styling with the design system
10. Optimize for both desktop and mobile viewports
```

--------------------------------

### TypeScript Example: Generic Type Constraints in Interface Definition

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/types/CLAUDE.md

Demonstrates using generic types with constraints in the `IElementData` interface. This ensures type-safe operations while maintaining flexibility by restricting `Type` and `Options` parameters, enhancing reusability and robustness.

```typescript
interface IElementData<Type extends ElementType, Options extends ElementOptions>
  extends Omit<Element, 'id'> {
  id: string
  type: Type
  options: Options
  elementId: number
}
```

--------------------------------

### Database Connection and Script Initialization

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/participant_activity_performance.ipynb

This code block initializes the Prisma database client, sets the 'DATABASE_URL' environment variable to connect to a PostgreSQL database, and establishes the database connection. It also defines a 'verbose' flag for controlling script output.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"
db.connect()

# Script settings
verbose = False
```

--------------------------------

### Generic Python Dependency Hashes

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/requirements.txt

A collection of SHA256 hashes for an unspecified Python dependency, ensuring the integrity of the package during installation. These hashes are typically used in `requirements.txt` files for secure and reproducible builds, preventing tampering or unexpected changes.

```Python Requirements
    --hash=sha256:75b4e316c5902d8163ef9d423b1c3f2f6252226d1aa5cd8a0a03a7d01ffc6268 \
    --hash=sha256:7b9853803278db3bdcc6cd5beca37815b133e9e77ff3d4733c247414e78eb8d1 \
    --hash=sha256:7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4 \
    --hash=sha256:81b0893a39bc5b865b8bf89e9ad7807e16717f19868e9d234bdaf9b1f1393868 \
    --hash=sha256:8efc84f01c1cd7e34b3fb310183e72fcdf55293ee736d679b6d35b35d80bba26 \
    --hash=sha256:8fae4ebbf95a179c1156fab0b142b74e4ba4204c87bde8d3d8b6f9c34c5825ef \
    --hash=sha256:99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b \
    --hash=sha256:9adbd9bb520c866e1bfd7e10e1880a1f7749f1f6e5017686a5fbb9b72cf69f82 \
    --hash=sha256:a1e01dcaab205fbece13c1410253a9eea1b1c9b61d237b6fa59bcc46e8e89343 \
    --hash=sha256:a8fc2de81ad835d999113ddf87d1ea2b0f4704cbd947c948d2f5513deafe5a7b \
    --hash=sha256:b83e16a5511d1b1f8a88cbabb1a6f6a499f82c062a4251892d9ad5d609863fb7 \
    --hash=sha256:bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171 \
    --hash=sha256:bfc085b28d62ff4009364e7ca34b80a9a080cbd97c2c0630bb5f7f770dae9414 \
    --hash=sha256:cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7 \
    --hash=sha256:e5eeca8067ad04bc8a2a8731183d51d7cbaac66d86085d5f4766ee6bf19c7f87 \
    --hash=sha256:e9e81fa9017eaa416c056e5d9e71be93d05e2c3c2ab308d23307a8bc4443c368 \
    --hash=sha256:ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587 \
    --hash=sha256:eacf3291e263d5a67d8c1a581a8ebbcfd6447204ef58828caf69a5e3e8c75990 \
    --hash=sha256:ec87f5f8aca726117a1c9b7083e7656a9d0d606eec7299cc067bb83d26f16e0c \
    --hash=sha256:f1659887361a7151f89e79b276ed8dff3d75877df906328f14d8bb40bb4f5101 \
    --hash=sha256:f9cf5ea551aec449206954b075db819f52adc1638d46a6738253a712d553c7b4
```

--------------------------------

### Run Common Development Commands for Email Templates

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/transactional/CLAUDE.md

This set of commands facilitates the development, building, previewing, and deployment of transactional email templates within the KlickerUZH project. It includes commands for local development, staging, and production environments, ensuring templates are correctly built and deployed to the database.

```bash
# Build all email templates (exports to HTML)
pnpm run build

# Start development server for previewing emails
pnpm run dev:email

# Deploy updated templates to the database (development)
pnpm run update-templates

# Deploy updated templates to the staging database
pnpm run update-templates:qa

# Deploy updated templates to the production database
pnpm run update-templates:prod
```

--------------------------------

### Internal Package Integrations

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Overview of core internal packages and their functionalities, highlighting their roles in GraphQL operations, database models, internationalization, shared components, and Markdown rendering, along with a note on compatibility.

```APIDOC
- @klicker-uzh/graphql: GraphQL operations and types
- @klicker-uzh/prisma: Database types and models
- @klicker-uzh/i18n: Internationalization messages
- @klicker-uzh/shared-components: Shared React components
- @klicker-uzh/markdown: Markdown rendering utilities

When making changes, ensure compatibility with these shared packages.
```

--------------------------------

### Define GraphQL Object Type with Pothos

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/graphql/CLAUDE.md

Example of defining a 'User' object type in a GraphQL schema using the Pothos schema builder. It demonstrates how to expose standard fields like 'id' and 'email', and a custom 'role' field with a resolver to fetch its value.

```typescript
const User = builder.objectType('User', {
  fields: (t) => ({
    id: t.exposeID('id'),
    email: t.exposeString('email'),
    role: t.field({
      type: UserRole,
      resolve: (user) => user.role,
    }),
  }),
})
```

--------------------------------

### Performance Optimization Considerations

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Key strategies for improving application performance, covering component optimization (memoization, virtualization, keys), data fetching (caching, pagination, optimistic UI), and bundle size reduction (lazy loading, dynamic imports).

```APIDOC
1. Component Optimization
   - Use React.memo for expensive renders
   - Implement virtualization for long lists
   - Use proper key props for lists
2. Data Fetching
   - Apply appropriate caching strategies
   - Use pagination for large datasets
   - Implement optimistic UI updates
3. Bundle Size
   - Lazy load components when possible
   - Use dynamic imports for large dependencies
   - Minimize unused imports
```

--------------------------------

### Conditional PWA Configuration for Production Environments

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/next-config/CLAUDE.md

This snippet demonstrates the correct way to conditionally apply PWA configuration using `withPWAInit` only when the `NODE_ENV` is not 'test'. This ensures PWA features are enabled for production builds while being disabled during testing, preventing unnecessary overhead.

```javascript
if (process.env.NODE_ENV !== 'test') {
  const withPWA = withPWAInit(
    getNextPWAConfig({ NODE_ENV: process.env.NODE_ENV })
  )
  nextConfig = withPWA(nextConfig)
}
```

--------------------------------

### Embed KlickerUZH Live Quiz Preparation Video

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/docs/docs/tutorials/live_quiz.mdx

This HTML iframe embeds a video tutorial from UZH MediaSpace demonstrating the preparation steps for a Live Quiz. It includes attributes for full-screen, autoplay, and security policies to ensure proper playback and user interaction.

```HTML
<iframe
  id="kmsembed-0_bfzstjdf"
  width="100%"
  height="400"
  src="https://uzh.mediaspace.cast.switch.ch/embed/secure/iframe/entryId/0_bfzstjdf/uiConfId/23448425/st/0"
  class="kmsembed"
  allowfullscreen
  webkitallowfullscreen
  mozAllowFullScreen
  allow="autoplay *; fullscreen *; encrypted-media *"
  referrerPolicy="no-referrer-when-downgrade"
  sandbox="allow-downloads allow-forms allow-same-origin allow-scripts allow-top-navigation allow-pointer-lock allow-popups allow-modals allow-orientation-lock allow-popups-to-escape-sandbox allow-presentation allow-top-navigation-by-user-activation"
  frameborder="0"
  title="KlickerUZH - Live Quiz Preparation"
></iframe>
```

--------------------------------

### Initialize Prisma DB Connection and Configure Environment

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/instance_activity_performance.ipynb

This code block initializes a Prisma client instance, which serves as the ORM for database interactions. It then sets the `DATABASE_URL` environment variable to establish a connection to a PostgreSQL database, specifically for the 'klicker-prod' instance. Finally, it connects to the database and sets a `verbose` flag for script execution, which is currently set to `False`.

```python
db = Prisma()

# set the environment variable DATABASE_URL to the connection string of your database
os.environ["DATABASE_URL"] = "postgresql://klicker:klicker@localhost:5432/klicker-prod"

db.connect()

# Script settings
verbose = False
```

--------------------------------

### Troubleshooting: Component Rendering Issues

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/frontend-manage/CLAUDE.md

Debugging steps for components that do not render as expected, including checks for conditional rendering logic, prop passing, data loading, and CSS conflicts.

```APIDOC
1. Check for conditional rendering logic bugs
2. Verify that props are correctly passed
3. Ensure that data is properly loaded before rendering
4. Check for CSS conflicts or responsive design issues
```

--------------------------------

### TypeScript Example: Polymorphic Type Union for Element Data

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/types/CLAUDE.md

Illustrates the common pattern of using type unions in TypeScript to handle polymorphic relationships, specifically for `ElementData`. This allows a single type to represent multiple distinct but related data structures, enhancing flexibility and type safety.

```typescript
export type ElementData =
  | ChoicesElementData
  | FreeTextElementData
  | NumericalElementData
// Additional types...
```

--------------------------------

### Running Custom Migration Scripts

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/prisma/CLAUDE.md

This snippet demonstrates the command-line interface for executing custom data migration scripts within the project. These scripts are typically used for complex data transformations that cannot be handled by standard SQL migrations and follow a specific naming convention.

```Shell
pnpm run script src/scripts/script-name.ts
```

--------------------------------

### Basic Next.js Configuration Implementation with next-config Package

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/next-config/CLAUDE.md

Demonstrates how to integrate `getNextBaseConfig` and `getNextPWAConfig` into a Next.js application's `next.config.js` file. It shows spreading the base configuration, adding application-specific redirects, and conditionally applying PWA capabilities based on the environment, ensuring PWA is active only outside of test environments.

```javascript
import { getNextBaseConfig, getNextPWAConfig } from '@klicker-uzh/next-config'

/** @type {import('next').NextConfig} */
let nextConfig = {
  ...getNextBaseConfig({
    BLOB_STORAGE_ACCOUNT_URL: process.env.BLOB_STORAGE_ACCOUNT_URL,
    NODE_ENV: process.env.NODE_ENV,
  }),
  // Application-specific configurations
  async redirects() {
    return [
      // Custom redirects...
    ]
  },
}

// Add PWA capabilities if not in test environment
if (process.env.NODE_ENV !== 'test') {
  const withPWA = withPWAInit(
    getNextPWAConfig({ NODE_ENV: process.env.NODE_ENV })
  )
  nextConfig = withPWA(nextConfig)
}

export default nextConfig
```

--------------------------------

### Compute Aggregated Weekday Activity for Courses

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/apps/analytics/src/notebooks/aggregated_course_analytics.ipynb

This snippet orchestrates the main computation logic. It first retrieves a DataFrame of all courses that have started in the past using `get_running_past_courses`. It then iterates through each course, printing its processing status, and calls `compute_weekday_activity` to calculate and store the aggregated weekday activity for that specific course in the database.

```python
# find all courses that started in the past
df_courses = get_running_past_courses(db)

# iterate over all courses and compute the participant course analytics
for idx, course in df_courses.iterrows():
    print(f"Processing course", idx, "of", len(df_courses), "with id", course["id"])

    # computation of activity per weekday
    compute_weekday_activity(db, course)
```

--------------------------------

### KlickerUZH GraphQL Package Development Commands

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/graphql/CLAUDE.md

This snippet lists common `pnpm` commands used for development tasks within the KlickerUZH GraphQL package. These commands facilitate building the project, generating TypeScript types from GraphQL schemas, running the application in development mode with auto-reloading, executing scripts, performing type checks, and running tests.

```Bash
# Build the package
pnpm run build

# Generate GraphQL types
pnpm run generate

# Run development mode with auto-reloading
pnpm run dev

# Run a script with proper environment
pnpm run script src/scripts/example.ts

# Check TypeScript types
pnpm run check

# Run tests
pnpm run test
```

--------------------------------

### TypeScript Enum for KlickerUZH Permission Levels

Source: https://github.com/uzh-bf/klicker-uzh/blob/v3/packages/util/CLAUDE.md

This TypeScript enum defines the distinct permission levels used throughout the KlickerUZH platform's hierarchical permission system. It specifies the access rights from 'NONE' (no access) to 'OWNER' (full administrative control), guiding how users interact with various objects.

```typescript
enum PermissionLevel {
  NONE = 'NONE',
  READ = 'READ',
  EXECUTE = 'EXECUTE',
  WRITE = 'WRITE',
  ADMIN = 'ADMIN',
  OWNER = 'OWNER',
}
```