Admin Web Portal
Relevant source files
The following files were used as context for generating this wiki page:The PeP5 Admin Web Portal is a Blazor Server application designed for teachers and administrators to manage the entire lifecycle of programming exams. It provides a user interface for creating, configuring, and reviewing programming exams and student attempts. Key functionalities include AI-powered exam generation, manual exam creation, management of exam codes for student access, and review of AI-graded student submissions.
The portal is the central hub for all administrative tasks, interacting with a suite of backend services to handle data persistence, AI integration, and code execution. It is styled with a custom theme that includes specific UI components for exam management, such as question navigation buttons and status indicators.
Sources: Services/ProgrammingExamService.cs, Services/OpenAIService.cs, wwwroot/css/app.css:1-17
Architecture
The Admin Web Portal is built on the Blazor Server hosting model. It relies on a service-oriented architecture to separate concerns. The primary components are the UI (Razor pages), ViewModels for data binding, backend services for business logic, and a database context for data access.
The diagram below illustrates the high-level interaction between the main components of the system.
Core Data Models
The application's functionality is built around a set of core data models representing programming exams, their structure, and student attempts. These entities are managed by Entity Framework Core.
The following Entity-Relationship diagram shows the main tables and their relationships for programming exams.
Key Entities
| Entity | Description | File |
|---|---|---|
ProgrammingExam | Represents a complete programming exam, including its title, duration, language, and associated tasks. | Models/ProgrammingExamModels.cs:8-53 |
ProgrammingTask | A specific problem or task within an exam, containing instructions, points, and test cases. | Models/ProgrammingExamModels.cs:83-112 |
TestCase | Defines an automated test for a ProgrammingTask with specific inputs and expected outputs. | Models/ProgrammingExamModels.cs:117-145 |
ProjectFile | A starter file (source code, data file, etc.) provided to the student at the beginning of the exam. | Models/ProgrammingExamModels.cs:149-179 |
ProgrammingExamAttempt | Records a student's attempt at an exam, tracking status, time, and final score. | Models/ProgrammingExamModels.cs:184-239 |
StudentProjectFile | The student's version of a project file, containing their code and modifications. | Models/ProgrammingExamModels.cs:253-275 |
TaskProgress | Tracks a student's progress and score on an individual task, including detailed AI evaluation results. | Models/ProgrammingExamModels.cs:280-330 |
Sources: Models/ProgrammingExamModels.cs
AI-Powered Features
A core feature of the Admin Web Portal is its integration with the OpenAI API to automate exam creation and code evaluation. This is handled by the OpenAIService.
Sources: Services/OpenAIService.cs
AI Exam Generation
Teachers can generate a complete programming exam project by providing a topic, language, task count, and difficulty. The OpenAIService constructs a detailed prompt and requests a structured JSON response from the OpenAI API.
The generation process is illustrated below:
The service is designed to be resilient, with retry logic and JSON sanitization to handle common AI response format issues.
Sources: Services/OpenAIService.cs:249-399, Services/ProgrammingExamService.cs:100-107
AI Code Evaluation
After a student submits an exam, their code can be evaluated by the AI. The EvaluateAllTasksAsync method orchestrates this by sending each task's code to the EvaluateCodeAsync method. This method sends the task instructions and the student's relevant code files to the OpenAI API for grading.
The AI is prompted to return a detailed evaluation in a specific JSON format, including a score, feedback, and analysis of code quality, correctness, and efficiency.
Evaluation Data Structure
The result of an AI evaluation for a single task is captured in the AICodeEvaluation class.
| Property | Type | Description |
|---|---|---|
TaskId | int | The ID of the task being evaluated. |
Score | decimal | The final score awarded for the task. |
CodeQualityScore | decimal | A score from 0-100 for code quality. |
CorrectnessScore | decimal | A score from 0-100 for logical correctness. |
EfficiencyScore | decimal | A score from 0-100 for solution efficiency. |
CompletionPercentage | decimal | The percentage of requirements met (0-100). |
Feedback | string | General constructive feedback. |
Strengths | string | What the student did well. |
AreasForImprovement | string | Specific areas to improve. |
SolutionSuggestion | string | A brief explanation of a better solution. |
CodeSnippets | List<CodeSnippetFeedback> | Specific feedback on parts of the code. |
Sources: Services/OpenAIService.cs:18-32, Services/ProgrammingExamService.cs:640-708
Code Execution Service
To run student code against test cases, the system uses the CodeExecutionService, which acts as a client for the Piston API, a third-party code execution engine.
The service is responsible for:
- Packaging student files into the format required by the Piston API.
- Handling language-specific configurations (e.g., entry point file names).
- Injecting data from
*.csvor*.txtfiles into the execution environment for tasks involving file I/O. - Executing code with standard input (
stdin). - Comparing the actual output against the expected output of a test case.
The following diagram shows the flow for running a single test case.
Configuration
The application uses a combination of database-stored settings and appsettings.json for configuration.
Platform Settings
Key-value settings are stored in the PlatformSettings table in the database. These are seeded with default values during the initial migration.
| Key | Default Value | Description |
|---|---|---|
PlatformName | PeP - Programming Examination Platform | The name of the application. |
Version | 5.0 | The current application version. |
OpenAIApiKey | (empty) | The API key for accessing the OpenAI service. |
DefaultExamDurationMinutes | 120 | Default duration for new exams. |
Sources: Data/ApplicationDbContext.cs:161-171, Migrations/20251130100008_InitialCreate.Designer.cs:407-450
Exam App Update Configuration
The configuration for the secure PeP.ExamApp client's auto-update mechanism is defined in appsettings.json. The web portal serves this information via an API endpoint.
{
"ExamAppUpdate": {
"Version": "1.1.0",
"DownloadUrl": "https://yourserver.com/downloads/PeP.ExamApp_Setup_1.1.0.exe",
"ReleaseNotes": "- Bug fixes\n- Performance improvements",
"ReleaseDate": "2025-12-22",
"IsMandatory": false,
"MinimumVersion": "1.0.0",
"Checksum": "sha256hashofinstallerfile"
}
}
This configuration is exposed via the GET /api/exam-app/update endpoint.
Sources: PeP.ExamApp/Installer/README.md:98-112, Controllers/ExamAppController.cs:30-52