Web Application Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The PeP (Programming Examination Platform) is a modern web application built on ASP.NET Core, designed for creating, administering, and automatically grading programming exams. The architecture comprises a Blazor Server web interface for administrators and teachers, a REST API to support a secure WPF desktop client for students, and a backend that integrates with external AI and code execution services.
The system is designed for containerized deployment on Google Cloud, utilizing services like Cloud Run for scalable web hosting and Cloud SQL for a managed database backend. This architecture provides a clear separation of concerns between the user interface, business logic, data access, and external service integrations.
Core Technology Stack
The application is built using a consistent and modern set of technologies centered around the .NET ecosystem.
| Component | Technology/Framework | Description | Source(s) |
|---|---|---|---|
| Backend Framework | ASP.NET Core | The foundation for the web application, controllers, and services. | Program.cs |
| Frontend Framework | Blazor Server | Powers the interactive web UI for teachers and administrators. | Program.cs:61 |
| UI Components | Radzen Blazor Components | Provides a rich set of pre-built UI components for the web interface. | Program.cs:64-68 |
| Database | SQL Server | The relational database used for storing all application data. | Program.cs:13 |
| Data Access | Entity Framework Core | The object-relational mapper (O/RM) for database interactions. | Program.cs:12-16 |
| Authentication | ASP.NET Core Identity | Manages user accounts, roles (Admin, Teacher, Student), and authentication. | Program.cs:19-25 |
| Deployment | Docker, Google Cloud Run | The application is containerized and deployed to Google Cloud's serverless platform. | DEPLOY-GCLOUD.md |
Sources: Program.cs, DEPLOY-GCLOUD.md
Application Startup and Services
Application startup is configured in Program.cs. It follows the standard ASP.NET Core dependency injection (DI) pattern to register and configure all necessary services.
Service Registration
Key services are registered with the DI container to be used throughout the application. A DbContextFactory is used for ApplicationDbContext to handle the Blazor Server execution model, which requires short-lived DbContext instances.
This diagram illustrates the registration of core services at startup.
Sources: Program.cs:10-80
Key Application Services
IExamService&IProgrammingExamService: Encapsulate the core business logic for managing standard and programming exams, attempts, and grading.IExamAppService: Provides logic specifically for the secure desktop client's API interactions.IUserService: Manages user-related operations.IOpenAIService: Integrates with the OpenAI API to generate exam content and perform AI-based code evaluations.ICodeExecutionService: Integrates with the Piston API to execute student code against test cases in a sandboxed environment.
Sources: Program.cs:77-80
Database Seeding
On startup, the application ensures the database is migrated to the latest version and seeds initial data, including user roles (Admin, Teacher, Student) and a default admin user. This process is designed to be idempotent.
Sources: Program.cs:99-158
Database and Data Models
The application uses Entity Framework Core with a code-first approach. All data models are defined as C# classes in the PeP.Models namespace, and the database schema is managed through EF Core migrations. ApplicationDbContext serves as the main bridge between the application and the database.
Core Data Model for Programming Exams
The following Entity Relationship Diagram (ERD) shows the key tables and relationships for the programming exam feature.
This diagram illustrates how a ProgrammingExam is composed of ProgrammingTasks and ProjectFiles. A student's ProgrammingExamAttempt contains their modified StudentProjectFiles and tracks their TaskProgress for each task.
Sources: Models/ProgrammingExamModels.cs, Data/ApplicationDbContext.cs:22-33, 160-278
External Service Integrations
The application leverages external APIs to provide advanced features like AI-powered evaluation and secure code execution.
OpenAI Service
The OpenAIService is responsible for all interactions with the OpenAI API. It is used for two primary purposes:
- Generating Programming Exams: The
GenerateProgrammingTasksAsyncmethod constructs a detailed system prompt and sends a request to an OpenAI model to generate a complete exam structure, including tasks, starter files, and test cases, based on a given topic. - Evaluating Student Code: The
EvaluateCodeAsyncmethod sends the task instructions and the student's code to an OpenAI model for a qualitative and quantitative assessment. It requests a structured JSON response containing scores, feedback, and suggestions.
The service retrieves the OpenAI API key from the PlatformSettings table in the database.
Sources: Services/OpenAIService.cs:14, 103, 330
This flowchart shows the process of evaluating a student's code for a single task.
Sources: Services/OpenAIService.cs:330-466
Piston API (Code Execution)
The CodeExecutionService uses the Piston API, a public code execution engine, to run student code in a sandboxed environment.
- Functionality: The
ExecuteCodeAsyncmethod takes a programming language, a dictionary of files, and optional standard input. It packages this into aPistonExecuteRequestand sends it to the Piston API. - Data Handling: For languages that support it, the service can inject data files (e.g., CSV, TXT) as string variables into a helper file, allowing student code to "read" files in the sandboxed environment.
- Response: The service parses the
PistonExecuteResponseto determine if the execution was successful, timed out, or resulted in a compilation/runtime error. It captures stdout, stderr, and exit codes.
Sources: Services/CodeExecutionService.cs:134-245, Services/CodeExecutionService.cs:382-535
API for Secure Desktop Client
The web application exposes a dedicated REST API for the PeP.ExamApp, a secure WPF desktop client used by students to take exams. This API is defined in ExamAppController.
API Endpoints
| Method | Endpoint | Description | Authorization |
|---|---|---|---|
GET | /api/exam-app/update | Provides update information for the desktop client. | Anonymous |
GET | /api/exam-app/code/{code} | Validates an exam code and returns exam details. | Student |
POST | /api/exam-app/authorize | Authorizes an exam attempt using the exam code and a teacher's password. Returns an authorization token. | Student |
POST | /api/exam-app/start | Starts the exam attempt using the authorization token. Returns a launch token and attempt ID. | Student |
Sources: Controllers/ExamAppController.cs:29-103
Exam Authorization and Start Flow
The following sequence diagram illustrates the flow from the student entering an exam code in the desktop app to launching the exam.
Deployment Architecture
The application is designed to be deployed to Google Cloud Platform using a container-based workflow. The deployment strategy is documented in DEPLOY-GCLOUD.md and automated via deploy-gcloud.ps1.
This diagram shows the high-level deployment architecture on Google Cloud.
- Cloud Run: Hosts the ASP.NET Core application as a stateless, auto-scaling container.
- Cloud SQL: Provides a managed SQL Server database instance.
- Secret Manager: Securely stores the database connection string, which is injected into the Cloud Run instance as an environment variable.
- Cloud Storage: Hosts the downloadable installer for the
PeP.ExamAppdesktop client. - Cloud Build: Automates the process of building the Docker image from the source code.
Sources: DEPLOY-GCLOUD.md, deploy-gcloud.ps1, PeP.ExamApp/Installer/README.md
Summary
The PeP5 web application architecture is a robust and scalable system that effectively separates concerns. It combines a Blazor Server UI for administrative tasks with a secure REST API for a student-facing desktop application. The use of dependency injection, a well-defined service layer, and EF Core promotes maintainability. By offloading complex tasks like code execution and AI evaluation to external services, the core application remains focused and lightweight. Finally, its design for containerized deployment on Google Cloud ensures a modern, scalable, and manageable hosting solution.