Skip to content

Test Performance Analysis

Jump to bottom
github-actions[bot] edited this page Apr 24, 2026 · 2 revisions

Test Performance Analysis

**Referenced Files in This Document** - [openai.ts](file://server/lib/openai.ts) - [routes.ts](file://server/routes.ts) - [schema.ts](file://shared/schema.ts) - [analytics.tsx](file://client/src/pages/analytics.tsx) - [performance-chart.tsx](file://client/src/components/dashboard/performance-chart.tsx) - [recent-tests-table.tsx](file://client/src/components/dashboard/recent-tests-table.tsx)

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction

This document provides comprehensive documentation for the test performance analysis system. It focuses on the analyzeTestPerformance function that processes student results to generate insights, including data structure requirements, AI-generated recommendations, identification of difficult questions, and statistical calculations. It also covers the JSON response schema, error handling, and practical examples of input and output formats.

Project Structure

The test performance analysis spans backend AI processing, API routing, and frontend analytics visualization:

  • Backend AI processing: analyzeTestPerformance function in the OpenAI library
  • API integration: route registration and usage in the Express server
  • Frontend analytics: dashboards and charts for performance visualization
  • Shared schemas: validation and typing for test and analytics data
graph TB
subgraph "Frontend"
FE_Analytics["Analytics Dashboard<br/>(analytics.tsx)"]
FE_PerfChart["Performance Chart<br/>(performance-chart.tsx)"]
FE_RecentTests["Recent Tests Table<br/>(recent-tests-table.tsx)"]
end
subgraph "Backend"
BE_Routes["Express Routes<br/>(routes.ts)"]
BE_OpenAI["OpenAI Library<br/>(openai.ts)"]
BE_Schema["Shared Schema<br/>(schema.ts)"]
end
FE_Analytics --> BE_Routes
FE_PerfChart --> BE_Routes
FE_RecentTests --> BE_Routes
BE_Routes --> BE_OpenAI
BE_OpenAI --> BE_Schema
Loading

Diagram sources

  • openai.ts
  • routes.ts
  • schema.ts
  • analytics.tsx
  • performance-chart.tsx
  • recent-tests-table.tsx

Section sources

  • openai.ts
  • routes.ts
  • schema.ts
  • analytics.tsx
  • performance-chart.tsx
  • recent-tests-table.tsx

Core Components

  • analyzeTestPerformance: Processes test results and returns average score, difficult questions, and recommendations
  • Route integration: Exposes analyzeTestPerformance via API endpoints
  • Frontend analytics: Visualizes performance metrics and insights
  • Shared schemas: Define data structures for validation and type safety

Section sources

  • openai.ts
  • routes.ts
  • schema.ts
  • analytics.tsx

Architecture Overview

The system integrates frontend dashboards with backend AI analysis through Express routes. The analyzeTestPerformance function sends processed test results to OpenAI's GPT-4o model and returns structured insights.

sequenceDiagram
participant Client as "Client App"
participant Routes as "Express Routes<br/>(routes.ts)"
participant OpenAI as "OpenAI Library<br/>(openai.ts)"
participant Model as "GPT-4o"
Client->>Routes : "POST /api/analyze-test-performance"
Routes->>OpenAI : "analyzeTestPerformance(testResults)"
OpenAI->>Model : "Chat Completions Request"
Model-->>OpenAI : "JSON Response"
OpenAI-->>Routes : "Parsed Analysis Results"
Routes-->>Client : "JSON Response"
Loading

Diagram sources

  • routes.ts
  • openai.ts

Detailed Component Analysis

analyzeTestPerformance Function

The analyzeTestPerformance function orchestrates AI-driven analysis of test results:

  • Accepts an array of student results with scores and per-question performance
  • Sends structured prompts to OpenAI GPT-4o
  • Returns standardized JSON with average score, hardest questions, and recommendations
  • Includes robust error handling with fallback calculations
flowchart TD
Start([Function Entry]) --> ValidateInput["Validate Input Parameters"]
ValidateInput --> InputValid{"Input Valid?"}
InputValid --> |No| ReturnFallback["Return Fallback Response"]
InputValid --> |Yes| CallOpenAI["Call OpenAI Chat Completions"]
CallOpenAI --> ParseResponse["Parse JSON Response"]
ParseResponse --> ParseSuccess{"Parse Success?"}
ParseSuccess --> |Yes| ReturnAnalysis["Return Analysis Results"]
ParseSuccess --> |No| FallbackParse["Fallback to Manual Calculation"]
FallbackParse --> ReturnFallback
ReturnAnalysis --> End([Function Exit])
ReturnFallback --> End
Loading

Diagram sources

  • openai.ts

Section sources

  • openai.ts

Data Structure Requirements

The analyzeTestPerformance function expects a specific array structure for test results:

Input Data Format:

  • Array of student result objects
  • Each student object includes:
    • studentId: number
    • score: number
    • answers: Array of question objects
      • questionId: number
      • score: number
      • question: string

Statistical Analysis:

  • Average score calculation: Sum of all student scores divided by number of students
  • Hardest questions: Identified by lowest average scores across questions
  • Recommendations: AI-generated teaching suggestions based on performance patterns

Section sources

  • openai.ts

JSON Response Schema

The analyzeTestPerformance function returns a standardized JSON object:

Response Fields:

  • averageScore: number (calculated average)
  • hardestQuestions: Array of question objects
    • questionId: number
    • question: string
    • avgScore: number
  • recommendations: string (teaching recommendations)

Example Response Structure: { "averageScore": 78.5, "hardestQuestions": [ { "questionId": 101, "question": "Explain Newton's laws of motion", "avgScore": 65.2 } ], "recommendations": "Focus on conceptual understanding of fundamental principles" }

Section sources

  • openai.ts

Frontend Integration and Visualization

The frontend analytics dashboard displays performance insights through:

  • Performance charts showing class vs school averages
  • Recent tests table with completion rates and average scores
  • AI-generated learning insights cards
graph LR
subgraph "Backend API"
API["/api/analyze-test-performance"]
end
subgraph "Frontend Components"
PerfChart["PerformanceChart"]
RecentTests["RecentTestsTable"]
Analytics["Analytics Dashboard"]
end
API --> PerfChart
API --> RecentTests
API --> Analytics
Loading

Diagram sources

  • routes.ts
  • performance-chart.tsx
  • recent-tests-table.tsx
  • analytics.tsx

Section sources

  • analytics.tsx
  • performance-chart.tsx
  • recent-tests-table.tsx

Dependency Analysis

The test performance analysis system has the following key dependencies:

graph TB
OpenAI["OpenAI Library<br/>(openai.ts)"]
Routes["Express Routes<br/>(routes.ts)"]
Schema["Shared Schema<br/>(schema.ts)"]
ClientAnalytics["Client Analytics<br/>(analytics.tsx)"]
Routes --> OpenAI
OpenAI --> Schema
ClientAnalytics --> Routes
Loading

Diagram sources

  • openai.ts
  • routes.ts
  • schema.ts
  • analytics.tsx

Section sources

  • openai.ts
  • routes.ts
  • schema.ts

Performance Considerations

  • API latency: OpenAI requests introduce network latency; implement caching for repeated analyses
  • Batch processing: Consider batching multiple test analyses to reduce overhead
  • Data volume: Large test result arrays may impact parsing performance; monitor JSON payload sizes
  • Error resilience: Built-in fallback mechanisms ensure system stability during AI service issues

Troubleshooting Guide

Common issues and resolutions:

JSON Parse Errors:

  • Symptom: Analysis returns fallback with error message
  • Cause: Malformed JSON response from OpenAI
  • Resolution: Verify input data format and retry analysis

AI Service Failures:

  • Symptom: Performance analysis unavailable
  • Cause: OpenAI API unavailability or rate limits
  • Resolution: System falls back to manual calculations using available data

Input Validation Issues:

  • Symptom: 400 Bad Request responses
  • Cause: Invalid test result structure
  • Resolution: Ensure all required fields are present and properly formatted

Section sources

  • openai.ts

Conclusion

The test performance analysis system provides a robust framework for processing student results and generating actionable insights. Through structured data formats, AI-powered analysis, and comprehensive error handling, it enables educators to identify learning gaps and improve instructional strategies effectively.

Clone this wiki locally