Client-Server Communication
Relevant source files
The following files were used as context for generating this wiki page:The PeP5 project utilizes a client-server architecture for its core functionality. The primary client is the PeP.ExamApp, a WPF desktop application, which communicates with the main PeP ASP.NET Core web application server. This communication happens over HTTP via a set of RESTful API endpoints. The server, in turn, communicates with external services like the OpenAI API for AI-driven features and the Piston API for remote code execution.
This document outlines the primary communication flows, the API structure, and the data models used for exchanging information between the client, the server, and external services.
System Architecture Overview
The communication architecture involves three main actors: the Exam App client, the PeP Web Server, and external APIs. The Exam App initiates all requests to the PeP server for authentication, exam management, and updates. The server handles business logic and, when necessary, acts as a proxy to call external services for specialized tasks like code evaluation or generation.
The following diagram illustrates the high-level communication paths between the different components.
This diagram shows the PeP Exam App client communicating with the PeP Web Server, which in turn communicates with external OpenAI and Piston APIs.
Sources: PeP.ExamApp/ExamAppApiClient.cs, Services/OpenAIService.cs, Services/CodeExecutionService.cs
Exam App Client Setup
The PeP.ExamApp client manages its connection to the server through the ExamAppState and ExamAppApiClient classes.
Connection State Management
The ExamAppState class is responsible for holding the server connection details and the current session state. When the client connects to a server, the ConfigureServer method is called. This method initializes an HttpClient with a shared CookieContainer to maintain the login session. It also instantiates the ExamAppApiClient which is used for all subsequent API calls.
Sources: PeP.ExamApp/ExamAppState.cs:19-38
API Client
The ExamAppApiClient class provides strongly-typed methods for interacting with the server's REST API. It encapsulates the logic for making HTTP requests and deserializing JSON responses. Key responsibilities include:
- Student login
- Fetching exam information
- Authorizing an exam session
- Starting an exam
- Submitting an exam
Sources: PeP.ExamApp/ExamAppApiClient.cs:7-13
Exam Authorization and Start Flow
A critical communication sequence is the process a student follows to start an exam. This involves multiple steps of authentication and authorization between the client and the server.
The sequence diagram below details the interactions between the student (via the Exam App), the API client, and the server controller.
This diagram shows the multi-step process for a student to start an exam, from login to receiving the final launch token.
Sources: PeP.ExamApp/ExamAppApiClient.cs:19-90, Controllers/ExamAppController.cs:58-100
Server API Endpoints
The ExamAppController on the server exposes endpoints specifically for the PeP.ExamApp client. All endpoints are under the /api/exam-app route.
| Method | Route | Description | Authorization |
|---|---|---|---|
GET | /update | Retrieves the latest version information for the Exam App. | Anonymous |
GET | /code/{code} | Fetches details for a specific exam code. | Student Role |
POST | /authorize | Authorizes a student to take an exam using an exam code and teacher password. Returns a short-lived authorization token. | Student Role |
POST | /start | Starts the exam attempt using an authorization token. Returns a launch token and exam details. | Student Role |
Sources: Controllers/ExamAppController.cs:12-100
Data Transfer Objects (DTOs)
Communication between the client and server relies on a set of record-based DTOs for requests and responses. These ensure type safety and clear contracts.
The diagram below shows the relationships between the DTOs used in the exam authorization flow.
This diagram illustrates the DTOs used for authorizing and starting an exam.
Sources: PeP.ExamApp/ExamAppApiClient.cs:92-111, Controllers/ExamAppController.cs:102-111
Application Update Service
The PeP.ExamApp has a built-in update mechanism that communicates with the server to check for new versions.
Update Check Flow
On startup, the UpdateService in the client sends a request to the /api/examapp/update endpoint, providing its current version. The server responds with details of the latest version if a newer one is available.
This diagram shows the sequence of events when the Exam App checks for a new version.
Sources: PeP.ExamApp/Services/UpdateService.cs:46-63, Controllers/ExamAppController.cs:30-49, PeP.ExamApp/App.xaml.cs:25-41
Update Configuration
The server's response to the update check is configured in its appsettings.json file, as documented in the installer's README.
| Key | Description |
|---|---|
Version | The latest version number (e.g., "1.1.0"). |
DownloadUrl | The public URL to the installer .exe file. |
ReleaseNotes | A string containing notes for the new release. |
ReleaseDate | The date of the release. |
IsMandatory | A boolean indicating if the update is required. |
Checksum | The SHA256 hash of the installer file for verification. |
Sources: PeP.ExamApp/Installer/README.md:73-84, Controllers/ExamAppController.cs:33-46
External API Communication
The PeP server also acts as a client to external APIs for specialized functionality.
OpenAI Service
The OpenAIService is used to generate exam questions and evaluate student code for programming exams. It communicates directly with the OpenAI API.
- Configuration: The service retrieves the OpenAI API Key and Model from
PlatformSettingsin the database. - Request: It constructs a
ChatMessagelist, including a detailed system prompt and a user prompt. - API Call: It uses the
OpenAIClientto send the request to the specified model. - Response Handling: The raw JSON response is parsed and sanitized. The
SanitizeJsonResponsemethod is crucial for cleaning up common AI-generated formatting issues like markdown fences and trailing commas.
Sources: Services/OpenAIService.cs:113-130, 545-566, 448-475
Code Execution Service (Piston API)
For running student code against test cases, the CodeExecutionService communicates with the Piston API, a third-party service for executing code in various languages.
The flow for executing code is as follows:
This diagram shows how the PeP server uses the CodeExecutionService to send code to the Piston API and receive the execution result.
Sources: Services/CodeExecutionService.cs:199-231
The service constructs a PistonExecuteRequest containing the language, version, and a list of files. It then POSTs this to the Piston API endpoint (https://emkc.org/api/v2/piston/execute) and parses the PistonExecuteResponse to determine the outcome, including stdout, stderr, and exit code.