Exam Creation & Management
Relevant source files
The following files were used as context for generating this wiki page:The Exam Creation & Management system provides the core functionality for teachers to design, generate, and administer exams within the PeP platform. It supports two distinct types of exams: traditional multiple-choice exams (Exam) and project-based programming exams (ProgrammingExam). The system is designed with flexibility, allowing for both manual creation of exam content and automated generation using the OpenAI service.
This module encompasses the data models that define exam structures, the services that handle business logic for creation and management, and the view models that facilitate data transfer from the user interface. It also includes mechanisms for generating unique access codes to control student access and for leveraging AI to evaluate programming exam submissions.
Data Models and Schema
The foundation of the exam system is a set of related data models that define the structure of exams, questions, tasks, and access codes. These models are configured in the ApplicationDbContext.
Sources: Data/ApplicationDbContext.cs:25-41, Data/ApplicationDbContext.cs:202-348
Entity Relationship Diagram
This diagram illustrates the relationships between the primary entities involved in both standard and programming exams.
Core Exam Entities
Exam (Standard Multiple-Choice)
Represents a traditional exam with a set of questions.
| Property | Type | Description |
|---|---|---|
Id | int | Primary key. |
Title | string | The title of the exam. |
CourseId | int | Foreign key to the Course entity. |
CreatedByUserId | string | Foreign key to the ApplicationUser who created the exam. |
DurationMinutes | int | The duration of the exam in minutes. Default is 120. |
TotalPoints | decimal | The total possible points for the exam. |
NumberOfQuestions | int | The number of questions in the exam. |
ScoringType | enum | Defines the scoring logic (e.g., AllOrNothing, PartialWithPenalty). |
ShuffleQuestions | bool | If true, the order of questions is randomized for each attempt. |
ShuffleChoices | bool | If true, the order of choices for each question is randomized. |
Questions | ICollection<Question> | Navigation property for the exam's questions. |
ExamCodes | ICollection<ExamCode> | Navigation property for the exam's access codes. |
Sources: Models/ExamModels.cs:42-95
ProgrammingExam
Represents a project-based exam with coding tasks, starter files, and test cases.
| Property | Type | Description |
|---|---|---|
Id | int | Primary key. |
Title | string | The title of the programming exam. |
Language | enum | The programming language for the exam (e.g., Java, Python). |
ProjectName | string | The name of the student's project. |
DurationMinutes | int | The duration of the exam in minutes. Default is 120. |
Tasks | ICollection<ProgrammingTask> | Navigation property for the exam's tasks. |
StarterFiles | ICollection<ProjectFile> | Navigation property for the project's initial file structure. |
ExamCodes | ICollection<ProgrammingExamCode> | Navigation property for the exam's access codes. |
Sources: Models/ProgrammingExamModels.cs:8-80
Exam Creation Process
Exams can be created either manually by a teacher or automatically using AI-powered generation. The CreateExamViewModel serves as the data transfer object for this process, accommodating both methods.
Sources: ViewModels/ExamViewModels.cs:70-128
Manual Creation
When a teacher creates an exam manually, they provide all the details, including questions and choices. The CreateExamViewModel contains a list of ManualQuestionViewModel objects, each with its own list of ManualChoiceViewModel objects. This structure allows the UI to dynamically build the exam form.
Sources: ViewModels/ExamViewModels.cs:131-166
AI-Powered Generation
The system can leverage OpenAIService to generate exam content. This is triggered when the UseAI flag in CreateExamViewModel is set to true.
AI Question Generation Flow
This flowchart shows the process of generating multiple-choice questions using AI.
The GenerateQuestionsAsync method in OpenAIService constructs a detailed prompt for the AI, requesting a specific number of questions in a strict JSON format. It includes retry logic to handle parsing failures or empty responses from the API.
Sources: Services/OpenAIService.cs:91-240, ViewModels/ExamViewModels.cs:119-121
AI Programming Exam Generation
For programming exams, the GenerateProgrammingTasksAsync method in OpenAIService is used. It takes a topic, language, and task count to generate a complete project structure.
The service returns a GeneratedProgrammingExam object, which includes:
ProjectName: A name for the project.Description: An overview of the exam.StarterFiles: A list ofGeneratedProjectFileobjects with file paths, content, and properties likeIsEntryPointandIsReadOnly.Tasks: A list ofGeneratedTaskobjects, each with instructions, points, and a list ofGeneratedTestCaseobjects.
This generated structure is then used by ProgrammingExamService to create the corresponding database entities (ProgrammingExam, ProgrammingTask, ProjectFile, TestCase).
Sources: Services/OpenAIService.cs:51-78, Services/OpenAIService.cs:262-411
Exam Access Management
Access to exams is controlled via unique, time-limited codes. There are separate entities for standard exams (ExamCode) and programming exams (ProgrammingExamCode).
| Entity | Key Properties | Description |
|---|---|---|
ExamCode | Code, ExamId, ExpiresAt, MaxUses | Grants access to a standard Exam. |
ProgrammingExamCode | Code, ProgrammingExamId, ExpiresAt, MaxUses | Grants access to a ProgrammingExam. |
Sources: Models/ExamModels.cs:254-290, Models/ProgrammingExamModels.cs:558-588
Code Generation and Validation
Teachers can generate codes for their exams. The ExamService.GenerateExamCodeAsync and ProgrammingExamService.GenerateProgrammingExamCodeAsync methods create a unique random code, associate it with an exam, and save it to the database.
When a student attempts to start an exam using the PeP.ExamApp, the code is validated through a series of API calls.
Sources: Services/ExamService.cs:469-496, Services/ProgrammingExamService.cs:389-417
Exam Code Validation Sequence
This diagram shows the sequence of events when the desktop ExamApp validates an exam code.
This initial lookup provides the student with details about the exam before they proceed with authorization.
Sources: PeP.ExamApp/ExamAppApiClient.cs:56-64, Controllers/ExamAppController.cs:58-69, Services/ExamAppService.cs:88-158
AI-Powered Code Evaluation
A key management feature for ProgrammingExam is the ability to automatically grade student submissions using AI. This process is initiated via ProgrammingExamService.EvaluateAttemptWithAIAsync.
AI Evaluation Workflow
The evaluation is performed on a per-task basis for a given ProgrammingExamAttempt.
Evaluation Criteria
The OpenAIService.EvaluateCodeAsync method instructs the AI to grade the code based on several criteria and return a structured AICodeEvaluation object.
| Property | Type | Description |
|---|---|---|
Score | decimal | The final score awarded for the task, capped at maxPoints. |
CodeQualityScore | decimal | A score from 0-100 for structure, readability, and naming. |
CorrectnessScore | decimal | A score from 0-100 for logical correctness. |
EfficiencyScore | decimal | A score from 0-100 for algorithmic efficiency. |
CompletionPercentage | decimal | A score from 0-100 indicating how much of the task was completed. |
Feedback | string | Detailed constructive feedback. |
Strengths | string | A summary of what the student did well. |
AreasForImprovement | string | Specific suggestions for improvement. |
CodeSnippets | List<CodeSnippetFeedback> | Specific code snippets with targeted comments. |
This structured feedback is then stored in the TaskProgress entity, providing both a score and detailed qualitative analysis for the student and teacher.
Sources: Services/OpenAIService.cs:20-37, Services/OpenAIService.cs:644-747, Models/ProgrammingExamModels.cs:405-442
Summary
The Exam Creation & Management system is a comprehensive module that empowers educators to create and manage a wide range of assessments. By integrating both manual and AI-driven creation workflows, it offers significant flexibility. The support for both traditional multiple-choice and complex programming exams, complete with starter projects and automated AI evaluation, makes it a powerful tool for modern technical education. The system's architecture, centered around the ExamService, ProgrammingExamService, and OpenAIService, provides a clear separation of concerns and a robust foundation for building, distributing, and grading exams.