Student Activity Tracking

Relevant source files

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

• backend/src/api/student-activity/student-activity.controller.ts
• frontend/src/api/collimator/hooks/student-activity/useTrackStudentActivity.ts
• frontend/src/pages/class/[classId]/session/[sessionId]/task/[taskId]/solve.tsx
• frontend/src/components/dashboard/ProgressList.tsx
• frontend/src/components/dashboard/StudentProgress.tsx
• frontend/src/api/collimator/generated/endpoints/solutions/solutions.ts
• frontend/src/api/collimator/hooks/solutions/useCreateSolution.ts

The Student Activity Tracking system is responsible for capturing, processing, and storing student interactions within the platform, primarily focusing on task solution submissions and other in-app events. This data is crucial for providing teachers with real-time and aggregated views of student progress within a class session. The system is designed to be robust, with support for batching multiple activities and handling offline scenarios to prevent data loss.

The tracked activities are consumed by the teacher's dashboard, where they are visualized in components like the ProgressList and the individual StudentProgress view. This allows educators to monitor class-wide performance and drill down into the specific work of each student.

High-Level Data Flow

There are two primary flows for tracking student work: a general-purpose activity batching system and a direct, single-solution submission system.

1. Batched Activity Tracking: A flexible system for tracking various activities. It uses the useTrackStudentActivity hook on the frontend to collect events, which are then sent in batches to the /api/student-activity endpoint. This is the preferred method for tracking general, potentially high-frequency events.
2. Direct Solution Submission: A more straightforward flow used specifically when a student submits a solution for a task. This uses the useCreateSolution hook to send a single solution directly to the /solutions/student endpoint.

The following diagram illustrates the direct solution submission flow, which is prominently used in the task-solving interface.

This diagram shows the sequence of events when a student submits a solution from the solve.tsx page.
Sources: frontend/src/pages/class/[classId]/session/[sessionId]/task/[taskId]/solve.tsx:103-130, frontend/src/api/collimator/hooks/solutions/useCreateSolution.ts

Frontend Implementation

Batched Activity Tracking (useTrackStudentActivity)

This hook provides a robust mechanism for tracking student activities, featuring batching and offline support.

• Purpose: To collect multiple student activities and send them to the backend in a single request. It is designed to be resilient to network failures.
• Logic: Activities are pushed into a global activitiesToTrack array. The hook attempts to send this batch to the backend. If the request fails (e.g., due to being offline), the activities remain in the array. An online event listener on the window object triggers a retry, ensuring that data is eventually sent when connectivity is restored.

The following diagram illustrates the internal logic of the useTrackStudentActivity hook.

Data Model: ActivityDto

The hook accepts an ActivityDto object for each activity to be tracked.

Field	Type	Description
type	string	The type of activity being tracked.
taskId	number	The ID of the associated task.
sessionId	number	The ID of the associated session.
appActivity	any	Application-specific activity data.
solution	Blob	A blob of the student's solution file at the time of the activity.

Sources: frontend/src/api/collimator/hooks/student-activity/useTrackStudentActivity.ts:9-11

Direct Solution Submission

When a student is on the solve.tsx page, submitting a solution triggers a more direct API call.

• saveSubmission Function: This function, located in solve.tsx, is responsible for preparing the submission data. It maps the passed and failed tests from the embedded application (e.g., Scratch) into the format expected by the backend.
• useCreateSolution Hook: The saveSubmission function calls the createSolution function returned by this hook. This hook abstracts the POST request to the /api/v0/classes/{classId}/sessions/{sessionId}/task/{taskId}/solutions/student endpoint.

Sources: frontend/src/pages/class/[classId]/session/[sessionId]/task/[taskId]/solve.tsx:90-130, frontend/src/api/collimator/hooks/solutions/useCreateSolution.ts

Backend API

Batched Activity Endpoint

The backend exposes a dedicated controller to handle batched student activities.

• Controller: StudentActivityController
• Endpoint: POST /student-activity
• Authentication: Requires an authenticated student (@StudentOnly()).

The endpoint is designed to receive multipart/form-data because it handles both structured JSON data (activities) and file uploads (solutions) in the same request.

Property	Description
activities	A JSON string array of TrackStudentActivitiesDto objects.
solutions	An array of Express.Multer.File objects.

The controller validates that the number of activity objects matches the number of solution files.

Sources: backend/src/api/student-activity/student-activity.controller.ts:27-71

DTO: TrackStudentActivitiesDto

This DTO defines the structure for the activities part of the multipart request.

Field	Type	Description
type	string	The type of activity.
taskId	number	The ID of the task.
sessionId	number	The ID of the session.
appActivity	any	Any application-specific data.
happenedAt	Date	The timestamp of when the activity occurred.

Sources: backend/src/api/student-activity/dto/track-activities.dto.ts, frontend/src/api/collimator/hooks/student-activity/useTrackStudentActivity.ts:30-37

Direct Solution Endpoint

This endpoint is used for submitting a single solution.

• Endpoint: POST /api/v0/classes/{classId}/sessions/{sessionId}/task/{taskId}/solutions/student
• Request Body: multipart/form-data containing a CreateSolutionDto.
  • tests: An array of test results.
  • file: The solution file blob.

Sources: frontend/src/api/collimator/generated/endpoints/solutions/solutions.ts:16-40

Progress Visualization

The data captured through activity tracking is ultimately displayed on the teacher's dashboard to show student progress.

The following diagram shows the relationship between the main components involved in displaying student progress.

ProgressList.tsx

This component provides a tabular overview of all students' progress within a single session.

• Data Fetching: It uses the useAllSessionSolutions, useClass, and useClassSession hooks to gather all necessary data.
• Data Aggregation: It merges data from multiple sources. It creates a comprehensive list of all students (both registered in the class and anonymous participants who have submitted solutions). It then groups each student's solutions by task.
• Display: It renders a DataTable where each row represents a student. Columns include the student's name, help requests, and a column for each task in the session, showing the status of their latest submission.

Sources: frontend/src/components/dashboard/ProgressList.tsx:201-233

StudentProgress.tsx

This component offers a detailed, task-by-task view of a single student's work.

• Functionality: It displays an accordion, with each item representing a task in the session. When a task is expanded, it renders the student's submitted solution for that task within an EmbeddedApp (e.g., the Scratch player).
• Data Logic: It uses useAllSessionSolutions to get all solutions for the session and then filters them to find the specific student's most relevant solution for each task using the ExistingStudentSolution.findSolutionToDisplay static method.

Sources: frontend/src/components/dashboard/StudentProgress.tsx:173-191