Getting Started

The PeP (Programming Examination Platform) is a comprehensive system for creating, administering, and evaluating programming exams. It features a web-based backend for instructors and a secure desktop client for students. The platform leverages AI for generating exam content and evaluating student submissions, and it is designed for cloud deployment.

This guide provides a high-level overview of the project's architecture, components, and setup procedures. It covers the backend services, the database schema, the secure ExamApp client, and the deployment process to Google Cloud. The system integrates with external services like the Piston API for code execution and the OpenAI API for AI-driven features.

Architecture Overview

The PeP5 system is composed of several key components: an ASP.NET Core web application, a WPF-based secure desktop ExamApp, a SQL Server database, and external APIs for code execution and AI functionality.

The following diagram illustrates the high-level architecture of the system.

Core Components

Sources: Program.cs, Data/ApplicationDbContext.cs, PeP.ExamApp/Installer/README.md, Services/OpenAIService.cs, Services/CodeExecutionService.cs

Backend Setup

The backend is an ASP.NET Core application that orchestrates all functionality. It relies on a SQL Server database and is configured through Program.cs.

Services

The application's functionality is modularized into several services that are registered for dependency injection.

// File: Program.cs:55-60
builder.Services.AddScoped<IExamService, ExamService>();
builder.Services.AddScoped<IExamAppService, ExamAppService>();
builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddScoped<IOpenAIService, OpenAIService>();
builder.Services.AddScoped<IProgrammingExamService, ProgrammingExamService>();
builder.Services.AddScoped<ICodeExecutionService, CodeExecutionService>();

Sources: Program.cs:55-60

Key services include:

• IProgrammingExamService: Manages the lifecycle of programming exams, tasks, attempts, and submissions.
• IOpenAIService: Handles all interactions with the OpenAI API, including question generation and AI code evaluation.
• ICodeExecutionService: Manages code execution via the Piston API.
• IExamAppService: Provides business logic for the secure ExamApp client, such as authorization and starting an exam.

Sources: Program.cs:55-60, Services/ProgrammingExamService.cs, Services/OpenAIService.cs, Services/CodeExecutionService.cs

Database Schema

The application uses Entity Framework Core to manage a SQL Server database. The schema is defined by model classes in PeP.Models and configured in ApplicationDbContext. The diagram below shows the key entities related to programming exams.

This diagram shows the relationships between a ProgrammingExam, its ProgrammingTasks, TestCases, and student ProgrammingExamAttempts.
Sources: Models/ProgrammingExamModels.cs, Data/ApplicationDbContext.cs:228-348

Configuration

Key application settings are managed through appsettings.json and seeded PlatformSetting entities in the database.

Sources: DEPLOY-GCLOUD.md:92-95, Data/ApplicationDbContext.cs:174, Services/OpenAIService.cs:122, PeP.ExamApp/Installer/README.md:96-105

PeP Exam App

The PeP.ExamApp is a secure desktop client for students. It provides a locked-down environment for taking exams, complete with anti-cheat measures and an integrated IDE based on the Monaco editor.

Building the Installer

The installer is created using Inno Setup and a PowerShell build script.

The build process is orchestrated by build-installer.ps1.

This diagram shows the flow of the installer build script.
Sources: PeP.ExamApp/Installer/build-installer.ps1, PeP.ExamApp/Installer/README.md:10-13

To build the installer, run the PowerShell script with a version number:

.\build-installer.ps1 -Version "1.0.0"

Sources: PeP.ExamApp/Installer/README.md:16-18

Auto-Update Mechanism

The ExamApp checks for updates on startup by calling a backend endpoint.

This sequence shows how the ExamApp checks for and receives update information from the backend.
Sources: Controllers/ExamAppController.cs:29-50, PeP.ExamApp/Installer/README.md:83-94

The update information is configured in the backend's appsettings.json:

{
  "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"
  }
}

Sources: PeP.ExamApp/Installer/README.md:96-105

Deployment

The application is designed to be deployed to Google Cloud using Cloud Run, Cloud SQL, and Cloud Storage.

Google Cloud Deployment Flow

The deployment process is automated with a PowerShell script (deploy-gcloud.ps1) and documented in DEPLOY-GCLOUD.md.

This diagram outlines the steps for deploying the PeP5 application to Google Cloud.
Sources: DEPLOY-GCLOUD.md, deploy-gcloud.ps1

Required Google Cloud Services

Sources: DEPLOY-GCLOUD.md:10-17, 39-47, 61-64, 92-95, 110-113, deploy-gcloud.ps1:34-40

Core AI & Code Execution Features

The platform's advanced features are powered by external APIs for AI and code execution.

AI-Powered Exam Generation

The OpenAIService can generate both programming tasks and multiple-choice questions based on a given topic, language, and difficulty. It sends a detailed system prompt to the OpenAI API and parses the structured JSON response.

Sources: Services/OpenAIService.cs:17-18, 111-118, 303-311

Code Execution and Evaluation

When a student runs their code or submits an exam, a two-stage process is initiated: execution and evaluation.

1. Execution: The CodeExecutionService sends the student's code to the Piston API, which compiles and runs it against predefined test cases, returning the output, errors, and execution status.
2. AI Evaluation: For the final submission, the OpenAIService sends the task instructions and the student's code to the OpenAI API for a qualitative review. The AI provides a score, detailed feedback, and analysis of code quality, correctness, and efficiency.

The following diagram illustrates this flow.

This sequence shows the interaction between the backend and external services for running code and performing AI-based grading.
Sources: Services/CodeExecutionService.cs:179-200, Services/OpenAIService.cs:645-661, Services/ProgrammingExamService.cs:853-863