Welcome to Collimator

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• frontend/README.md
• backend/README.md
• frontend/package.json
• apps/scratch/craco.config.js
• frontend/src/pages/task/[taskId]/edit.tsx
• frontend/src/pages/class/[classId]/session/[sessionId]/task/[taskId]/solve.tsx
• frontend/src/components/dashboard/CodeView.tsx
• e2e/tests/task/task-management.spec.ts
• e2e/tests/users/user-management.spec.ts
• apps/scratch/src/pages/tests/Solve.spec.tsx
• frontend/content/compiled-locales/en.json

Collimator is a web-based platform designed for building and managing programming tasks, primarily for educational purposes. The user-facing application is named "ClassMosaic". It enables teachers to create classes, manage sessions, and design tasks that students can solve directly in the browser. A core feature is its deep integration with a customized version of Scratch, allowing for the creation, submission, and analysis of block-based programming projects.

The system is architected as a monorepo containing a Next.js frontend, a NestJS backend, and a specialized Scratch application. It supports features like user management (teachers, admins), class and session management, task creation with reference solutions, student progress tracking, and advanced solution analysis, including dissimilarity analysis. Authentication is handled via OpenID Connect, with Microsoft being a specified provider.

Sources: frontend/README.md, backend/README.md, frontend/content/compiled-locales/en.json:175, frontend/src/pages/login/oidc-redirect.tsx:32

System Architecture

Collimator is a multi-package monorepo. The primary components are the frontend, backend, and the embedded apps/scratch application. End-to-end testing is managed within the e2e directory.

This diagram shows the high-level architecture of the Collimator project.

Frontend

The frontend is a Next.js application written in TypeScript. It serves as the main user interface for both teachers and students.

Sources: frontend/README.md

Key Technologies & Features:

• Framework: Next.js with React 19.
• UI: React-Bootstrap and PrimeReact.
• State Management: SWR for data fetching and caching.
• Forms: React Hook Form with Yup for validation.
• Internationalization (i18n): react-intl (from FormatJS) is used for localization, with scripts to extract and compile message strings. English (en.json) and French (fr.json) locales are provided.
• Routing: File-based routing provided by Next.js under the frontend/src/pages directory. For example, frontend/src/pages/task/[taskId]/edit.tsx maps to the URL /task/:taskId/edit.
• Testing: Jest for unit tests and Playwright for component and end-to-end tests.

Sources: frontend/package.json:42-63, frontend/package.json:11-14, frontend/src/pages/task/[taskId]/edit.tsx, frontend/content/compiled-locales/en.json, frontend/content/compiled-locales/fr.json

Backend

The backend is a server-side application built with the NestJS framework and TypeScript. It provides the API that the frontend consumes for all data operations.

Key Features:

• Framework: NestJS, a progressive Node.js framework.
• Database: The specific database is not detailed in the provided files, but it interacts with a database to store users, tasks, solutions, etc.
• API: Exposes a RESTful API for managing resources like users, classes, sessions, and tasks.
• Authentication: Handles user authentication logic, connecting with OpenID Connect providers.

Standard scripts are provided for development, testing, and production builds.

Script	Description
start	Runs the application.
start:dev	Runs the application in watch mode.
start:prod	Runs the application in production mode.
test	Runs unit tests.
test:e2e	Runs end-to-end tests.

Sources: backend/README.md

Scratch Integration

A crucial part of Collimator is the integration of a heavily customized Scratch application, located in apps/scratch. This is a React application, configured with craco.config.js to manage the complex build process of Scratch.

The Scratch app is embedded into the frontend using an <iframe> and communicates with the parent Next.js application via iframe-rpc-react. This allows the main application to load tasks, get submissions, and control the Scratch environment.

Sources: apps/scratch/craco.config.js, frontend/src/components/dashboard/CodeView.tsx:16, apps/scratch/src/pages/tests/Solve.spec.tsx:20-27

The Scratch app has several modes, determined by the URL it's loaded from:

• /solve: For students to solve a task. The UI is restricted, and block configurations cannot be changed.
• /edit: For teachers to create or edit a task. It provides full access to configure allowed blocks, freeze blocks, and set up the initial state.
• /show: A read-only view to display a student's solution code.

Sources: frontend/src/pages/task/[taskId]/detail.tsx:28-34, frontend/src/pages/class/[classId]/session/[sessionId]/task/[taskId]/solve.tsx:30-36, frontend/src/components/dashboard/CodeView.tsx:36-42, apps/scratch/src/pages/tests/Solve.spec.tsx, apps/scratch/src/pages/tests/Edit.spec.tsx, apps/scratch/src/pages/tests/Show.spec.tsx

This sequence diagram illustrates how the frontend loads a task into the embedded Scratch application.

Core Features

User Management

The system supports different user roles, primarily ADMIN and TEACHER. End-to-end tests demonstrate the ability for an admin to perform full CRUD operations on users, including creating, updating, and deleting both teachers and admins. It's also possible to promote a teacher to an admin or demote an admin to a teacher.

Sources: e2e/tests/users/user-management.spec.ts, frontend/src/pages/user/[userId]/edit.tsx

Task Management

Teachers can create, view, edit, and delete tasks. A task consists of a title, description, type (e.g., SCRATCH), and a task file (a .sb3 blob for Scratch).

The task creation and editing process happens in a dedicated form (TaskForm.tsx) which opens a modal containing the embedded Scratch editor (/edit). In this editor, the teacher can define the initial project, set constraints on which blocks can be used, and define reference solutions.

This flowchart shows the process of creating and editing a task.

Session and Solution Analysis

Teachers can create sessions within a class, assigning one or more tasks to it. Students can then join the session to solve these tasks.

As students submit solutions, the platform analyzes them. Key analysis features include:

• Progress Tracking: Teachers can view the progress of all students in a session, including which tasks they have attempted and their success.
• Code Viewing: Teachers can view the code of any submission in a read-only Scratch interface.
• Dissimilarity Analysis: The system can identify and display a specified number of the most dissimilar solutions for a given task, helping teachers find a variety of approaches. This can be done for all sub-tasks or filtered to a specific one.

Sources: e2e/tests/sessions/session-analysis.spec.ts, frontend/src/components/dashboard/DissimilarityAnalysis.tsx, frontend/src/components/dashboard/CodeView.tsx

Testing

The project has a comprehensive testing strategy.

• Unit Tests: Jest is used for unit testing components and logic.
• Component Tests: Playwright is configured for component testing (playwright-ct.config.ts).
• End-to-End (E2E) Tests: The e2e directory contains Playwright tests that cover major user flows like user management, task management, and session analysis. These tests interact with the live application, mock API responses, and assert UI state.

The frontend/package.json file contains various scripts for running these tests, including options for generating coverage reports.

Sources: frontend/package.json:15-28, e2e/tests/task/task-management.spec.ts, e2e/tests/users/user-management.spec.ts, e2e/tests/sessions/session-analysis.spec.ts

Summary

Collimator (ClassMosaic) is a robust educational platform for teaching programming with Scratch. Its architecture separates concerns between a Next.js frontend, a NestJS backend, and a highly integrated Scratch application. The system provides a rich feature set for teachers to manage their curriculum and analyze student work, supported by a strong testing foundation to ensure reliability.