Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The PeP5 (Programming Examination Platform) is a comprehensive system designed for creating, administering, and evaluating programming exams. It follows a client-server architecture, comprising a .NET-based backend, a relational database, a secure WPF desktop client for students, and an integrated AI service for content generation and code evaluation. This architecture separates the core business logic and data management on the server from the user-facing exam environment, ensuring security and scalability.
The backend is built with ASP.NET Core and exposes a RESTful API for the client application. It handles user authentication, exam management, and the entire exam lifecycle from authorization to submission and grading. A key feature is its integration with OpenAI's services to automate the creation of programming tasks and provide AI-driven feedback on student code submissions.
High-Level System Components
The system is composed of four primary components that interact to deliver the exam experience. The ASP.NET Core backend serves as the central hub, coordinating between the database, the AI service, and the student's exam application.
This diagram shows the main components: the WPF client, the backend server, the database, and the external OpenAI service.
- PeP.ExamApp WPF Client: A secure desktop application used by students to take exams. It communicates with the backend via a REST API.
- ASP.NET Core Backend: The core of the application, handling all business logic, data persistence, and communication with external services.
- SQL Server Database: Persists all application data, including users, courses, exams, attempts, and AI evaluation results. Entity Framework Core is used as the ORM.
- OpenAI API: An external service used for generating exam content and evaluating student code submissions.
Sources: Controllers/ExamAppController.cs, Services/OpenAIService.cs, Data/ApplicationDbContext.cs, PeP.ExamApp/Pages/ExamCodePage.xaml.cs
Database Schema
The data model is defined using Entity Framework Core and is centered around the concept of ProgrammingExam and ProgrammingExamAttempt. The schema supports both standard multiple-choice exams and project-based programming exams.
Sources: Data/ApplicationDbContext.cs, Models/ProgrammingExamModels.cs, Models/ExamModels.cs, Models/ExamAppModels.cs
Core Programming Exam ER Diagram
The following diagram illustrates the key entities and their relationships for the programming exam feature.
This ER diagram shows the relationships between exams, tasks, attempts, and other related data models.
Key Data Models
| Entity | Description | Source File |
|---|---|---|
ProgrammingExam | Defines a project-based programming exam, including its title, duration, language, and associated tasks. | Models/ProgrammingExamModels.cs:7-81 |
ProgrammingTask | Represents a single problem or requirement within a ProgrammingExam. | Models/ProgrammingExamModels.cs:100-126 |
TestCase | An automated test case with input and expected output to evaluate a ProgrammingTask. | Models/ProgrammingExamModels.cs:131-160 |
ProjectFile | A starter/template file provided to the student at the beginning of an exam. | Models/ProgrammingExamModels.cs:165-197 |
ProgrammingExamAttempt | Records a student's attempt at a programming exam, including start/end times and final score. | Models/ProgrammingExamModels.cs:209-267 |
StudentProjectFile | The student's version of a project file, containing their code and modifications. | Models/ProgrammingExamModels.cs:281-303 |
TaskProgress | Tracks a student's progress and AI-generated score/feedback for a specific ProgrammingTask. | Models/ProgrammingExamModels.cs:308-361 |
CodeSubmission | A snapshot of all student files at a point in time (e.g., auto-save, manual run). | Models/ProgrammingExamModels.cs:400-418 |
ExamAppAuthorization | A temporary token authorizing a student to start a specific exam from the secure client. | Models/ExamAppModels.cs:5-36 |
Backend Architecture
The backend is structured into several layers: Controllers (API), Services (Business Logic), and Data (Persistence).
Sources: Services/ProgrammingExamService.cs, Services/OpenAIService.cs, Controllers/ExamAppController.cs
Service Layer
The service layer encapsulates the core business logic.
IProgrammingExamService: Manages all operations related to programming exams, such as creating exams, starting attempts, saving student files, and submitting the final work. It acts as a central orchestrator for programming exam logic.
Sources: Services/ProgrammingExamService.cs:7-79IOpenAIService: Provides an abstraction over the external OpenAI API. It is responsible for two main functions: generating new programming exam tasks and evaluating student code submissions for grading and feedback.
Sources: Services/OpenAIService.cs:11-16IExamAppService: Handles the authorization flow for thePeP.ExamAppclient, validating exam codes and issuing secure tokens.
Sources: Controllers/ExamAppController.cs:17-24
API Layer (ExamAppController)
The ExamAppController provides the necessary REST endpoints for the PeP.ExamApp client to function. It handles requests for updates, exam information, authorization, and starting an exam session.
| Endpoint | Method | Description | Source |
|---|---|---|---|
api/exam-app/update | GET | Provides update information for the client application, read from configuration. | Controllers/ExamAppController.cs:30-46 |
api/exam-app/code/{code} | GET | Retrieves details about an exam based on a given code. | Controllers/ExamAppController.cs:63-72 |
api/exam-app/authorize | POST | Authorizes a student to take an exam by validating the exam code and teacher password, returning an authorization token. | Controllers/ExamAppController.cs:74-85 |
api/exam-app/start | POST | Starts an exam attempt using a valid authorization token and returns a launch token. | Controllers/ExamAppController.cs:87-98 |
Sources: Controllers/ExamAppController.cs:11-109
Client Application Flow
The PeP.ExamApp is a WPF desktop application that guides the student through the process of starting a secure exam. The flow involves multiple steps of validation and authorization with the backend API.
Exam Authorization and Start Sequence
This diagram shows the sequence of interactions between the student, the WPF client, and the backend API to begin an exam.
This sequence illustrates the multi-step process from entering an exam code to launching the secure exam environment.
Sources: Controllers/ExamAppController.cs:63-98, PeP.ExamApp/Pages/ExamCodePage.xaml.cs:33-60, PeP.ExamApp/Pages/TeacherAuthPage.xaml.cs:28-56, PeP.ExamApp/Pages/AntiCheatPage.xaml.cs:72-79
AI Integration (OpenAIService)
A significant feature of the PeP5 architecture is its integration with OpenAI for automating educational tasks. This is handled exclusively by the OpenAIService.
Sources: Services/OpenAIService.cs
AI-Powered Exam Generation
The system can generate a full programming exam, including tasks, starter files, and test cases, based on a simple topic prompt.
This flowchart shows the process of generating a programming exam using AI.
Sources: Services/OpenAIService.cs:282-401
AI-Powered Code Evaluation
After a student submits an exam, their code can be evaluated by the AI. The service sends the task instructions and the student's code to the OpenAI API and receives a structured JSON response containing scores and feedback.
This flowchart shows the process of evaluating student code using AI.
The evaluation result is captured in the AICodeEvaluation class, which includes detailed metrics.
| Field | Type | Description |
|---|---|---|
Score | decimal | The final score awarded for the task. |
CodeQualityScore | decimal | A score from 0-100 for code structure and readability. |
CorrectnessScore | decimal | A score from 0-100 for logical correctness. |
EfficiencyScore | decimal | A score from 0-100 for algorithmic efficiency. |
CompletionPercentage | decimal | An estimate of how much of the task was completed. |
Feedback | string | General constructive feedback. |
Strengths | string | A summary of what the student did well. |
AreasForImprovement | string | Specific suggestions for improvement. |
SolutionSuggestion | string | A brief explanation of a better or alternative solution. |
CodeSnippets | List<CodeSnippetFeedback> | A list of specific code snippets with targeted comments. |
Sources: Services/OpenAIService.cs:19-35, Models/ProgrammingExamModels.cs:342-360
Conclusion
The PeP5 architecture is a modern, well-structured system that effectively separates concerns between a secure client, a robust backend, and a powerful external AI service. The use of a service-oriented approach in the backend (ProgrammingExamService, OpenAIService) promotes modularity and maintainability. The database schema is thoughtfully designed to support complex relationships required for both traditional and programming exams. The integration with OpenAI for exam generation and code evaluation is a core architectural feature that provides significant value by automating key pedagogical tasks. The secure authorization flow for the desktop client ensures the integrity of the exam environment.