Skip to content

Result Analysis & Tracking

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

Result Analysis & Tracking

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

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
  10. Appendices

Introduction

This document describes the result analysis and tracking system in PersonalLearningPro. It covers the analytics dashboard components for individual and class performance metrics, the data aggregation processes for grades and averages, visualization components for charts and trends, result export/report generation capabilities, integration with learning analytics for knowledge gap identification, filtering and sorting options, and privacy/access controls aligned with user roles.

Project Structure

The analytics and result tracking functionality spans client-side dashboards and server-side storage and AI analysis:

  • Client dashboards render performance charts, recent tests, and top students.
  • Server-side storage persists analytics records and exposes operations for retrieving analytics by user or test.
  • AI integration computes insights from test performance data.
  • Shared schemas define the analytics record structure used across client and server.
graph TB
subgraph "Client"
A["Analytics Page<br/>analytics.tsx"]
B["Performance Chart<br/>performance-chart.tsx"]
C["Top Students<br/>top-students.tsx"]
D["Recent Tests Table<br/>recent-tests-table.tsx"]
E["Dashboard Pages<br/>dashboard.tsx, admin-dashboard.tsx, parent-dashboard.tsx"]
end
subgraph "Server"
F["Storage Layer<br/>storage.ts"]
G["OpenAI Integration<br/>openai.ts"]
H["Routes<br/>routes.ts"]
end
subgraph "Shared"
I["Schemas<br/>schema.ts"]
end
A --> B
A --> C
E --> B
E --> D
B --> F
C --> F
D --> F
F --> G
H --> F
F --> I
Loading

Diagram sources

  • analytics.tsx
  • performance-chart.tsx
  • top-students.tsx
  • recent-tests-table.tsx
  • dashboard.tsx
  • admin-dashboard.tsx
  • parent-dashboard.tsx
  • storage.ts
  • openai.ts
  • routes.ts
  • schema.ts

Section sources

  • analytics.tsx
  • performance-chart.tsx
  • top-students.tsx
  • recent-tests-table.tsx
  • dashboard.tsx
  • admin-dashboard.tsx
  • parent-dashboard.tsx
  • storage.ts
  • openai.ts
  • schema.ts
  • routes.ts

Core Components

  • Analytics dashboard page renders class performance by subject, top students, completion rates, subject distribution, and AI-generated insights.
  • Performance chart displays class vs school averages per subject using bar charts.
  • Top students panel lists high-achieving students with scores.
  • Recent tests table shows test status, completion rate, and average score where available.
  • Storage layer supports creating and retrieving analytics records by user or test.
  • OpenAI integration analyzes test performance to compute averages, identify hard questions, and generate recommendations.
  • Shared schema defines the analytics record shape.

Section sources

  • analytics.tsx
  • performance-chart.tsx
  • top-students.tsx
  • recent-tests-table.tsx
  • storage.ts
  • openai.ts
  • schema.ts

Architecture Overview

The analytics pipeline integrates client dashboards, server storage, and AI insights:

  • Client dashboards fetch data via React Query and render charts and tables.
  • Server routes expose endpoints for user and test operations; analytics persistence is handled by storage.
  • AI analysis consumes test results to produce insights and recommendations.
sequenceDiagram
participant U as "User"
participant P as "Analytics Page<br/>analytics.tsx"
participant PC as "Performance Chart<br/>performance-chart.tsx"
participant ST as "Storage<br/>storage.ts"
participant OA as "OpenAI<br/>openai.ts"
U->>P : Navigate to Analytics
P->>PC : Render chart with data
PC->>ST : Query class/school averages
ST-->>PC : Analytics records
PC-->>U : Bar chart rendered
U->>OA : Trigger performance analysis
OA-->>U : Insights and recommendations
Loading

Diagram sources

  • analytics.tsx
  • performance-chart.tsx
  • storage.ts
  • openai.ts

Detailed Component Analysis

Analytics Dashboard Page

  • Purpose: Aggregates multiple analytics widgets into a single view.
  • Features:
    • Class performance by subject via a bar chart component.
    • Top students leaderboard.
    • Test completion rate pie chart.
    • Subject distribution pie chart.
    • AI-generated insights with tabs for class and individual views.
  • Data sources: Uses mock data for visualizations; connects to backend APIs via query keys.
flowchart TD
Start(["Render Analytics"]) --> Perf["Render Performance Chart"]
Start --> Top["Render Top Students"]
Start --> Completion["Render Test Completion Pie"]
Start --> Subject["Render Subject Distribution Pie"]
Start --> Insights["Render AI Insights Tabs"]
Perf --> End(["Dashboard Ready"])
Top --> End
Completion --> End
Subject --> End
Insights --> End
Loading

Diagram sources

  • analytics.tsx

Section sources

  • analytics.tsx

Performance Chart Component

  • Purpose: Visualizes class average versus school average per subject.
  • Data model: Accepts an array of objects with subject, classAverage, and schoolAverage.
  • Behavior:
    • Disabled by default until backend endpoint is implemented; uses mock data.
    • Applies theme-aware styling and tooltips.
  • Integration: Connects to a query key for class performance data.
classDiagram
class PerformanceChart {
+useQuery()
+renderBarChart()
+mockData
}
class Storage {
+getAnalyticsByUser(userId)
+getAnalyticsByTest(testId)
}
PerformanceChart --> Storage : "queries analytics"
Loading

Diagram sources

  • performance-chart.tsx
  • storage.ts

Section sources

  • performance-chart.tsx
  • storage.ts

Top Students Component

  • Purpose: Displays top-performing students with avatar, name, class, and score.
  • Behavior:
    • Disabled by default until backend endpoint is implemented; uses mock data.
    • Skeleton loading while data is fetching.

Section sources

  • top-students.tsx

Recent Tests Table

  • Purpose: Lists recent tests with status, completion rate, and average score.
  • Features:
    • Status badges for completed, in-progress, scheduled, canceled.
    • Progress bars for completion rate.
    • Action links to view test details.
  • Behavior:
    • Fetches test data via query key.
    • Shows empty state with a link to create a test.

Section sources

  • recent-tests-table.tsx

Dashboard Pages Integration

  • Dashboard pages integrate performance charts and recent tests tables for quick insights.
  • Admin and parent dashboards include additional analytics visuals (e.g., academic progression line chart).

Section sources

  • dashboard.tsx
  • admin-dashboard.tsx
  • parent-dashboard.tsx

Storage and Analytics Records

  • Storage operations:
    • Create analytics record.
    • Retrieve analytics by user or test.
  • Analytics record fields:
    • userId, testId, weakTopics, strongTopics, recommendedResources, insightDate.
erDiagram
ANALYTICS {
int id PK
int userId
int testId
string[] weakTopics
string[] strongTopics
string[] recommendedResources
date insightDate
}
Loading

Diagram sources

  • storage.ts
  • schema.ts

Section sources

  • storage.ts
  • schema.ts

AI-Generated Learning Insights

  • Functionality: analyzeTestPerformance computes average score, identifies hardest questions, and generates recommendations.
  • Inputs: Array of student results with studentId, score, and answers.
  • Output: averageScore, hardestQuestions, recommendations.
  • Fallback: Computes average score if AI parsing fails.
sequenceDiagram
participant C as "Client"
participant R as "Routes<br/>routes.ts"
participant O as "OpenAI<br/>openai.ts"
C->>R : POST analyze test performance
R->>O : analyzeTestPerformance(testResults)
O-->>R : {averageScore, hardestQuestions, recommendations}
R-->>C : JSON response
Loading

Diagram sources

  • routes.ts
  • openai.ts

Section sources

  • openai.ts
  • routes.ts

Data Aggregation Processes

  • Class vs School Averages:
    • Aggregated per subject from analytics records.
    • Visualized using bar charts.
  • Test Completion and Subject Distribution:
    • Derived from test and analytics datasets.
    • Visualized using pie charts.
  • Average Scores:
    • Computed either by AI analysis or fallback logic.

Section sources

  • performance-chart.tsx
  • analytics.tsx
  • openai.ts

Visualization Components

  • Bar charts for class vs school averages.
  • Pie charts for completion rates and subject distributions.
  • Line charts for academic progression (parent dashboard).
  • Tabbed UI for class vs individual insights.

Section sources

  • analytics.tsx
  • parent-dashboard.tsx

Filtering and Sorting Options

  • Filtering:
    • Dropdown menus for grouping and state filters in student directory.
    • Cohort-based comparisons can be achieved by selecting specific classes or groups.
  • Sorting:
    • Sorting options for student lists and tables are available in dashboards.
  • Time-series analysis:
    • Academic progression line chart enables trend analysis over time.

Section sources

  • analytics.tsx
  • parent-dashboard.tsx
  • mockData.ts
  • config.ts

Result Export, Report Generation, and Sharing

  • Admin dashboard includes report generation cards for academic performance, attendance, exam results, and calendar.
  • Download actions for recent reports are exposed in the admin UI.
  • Sharing capabilities are not implemented in the current codebase; future enhancements can leverage these report endpoints.

Section sources

  • admin-dashboard.tsx

Privacy and Access Controls

  • Role-specific data configuration:
    • Defines role-specific attributes such as classId, subjects, institutionId, studentId.
  • Access patterns:
    • Dashboards and analytics are role-aware; UI surfaces differ by role.
    • Storage operations support retrieving analytics by user or test, enabling role-based filtering.

Section sources

  • config.ts
  • storage.ts

Dependency Analysis

  • Client dashboards depend on:
    • React Query for data fetching.
    • Recharts for visualization.
    • Theme context for dark/light mode styling.
  • Server depends on:
    • Storage abstraction for analytics persistence.
    • OpenAI integration for insights.
    • Routes for exposing endpoints.
graph LR
PC["performance-chart.tsx"] --> ST["storage.ts"]
TS["top-students.tsx"] --> ST
RT["recent-tests-table.tsx"] --> ST
OA["openai.ts"] --> ST
R["routes.ts"] --> ST
SC["schema.ts"] --> ST
Loading

Diagram sources

  • performance-chart.tsx
  • top-students.tsx
  • recent-tests-table.tsx
  • storage.ts
  • openai.ts
  • routes.ts
  • schema.ts

Section sources

  • performance-chart.tsx
  • top-students.tsx
  • recent-tests-table.tsx
  • storage.ts
  • openai.ts
  • routes.ts
  • schema.ts

Performance Considerations

  • Client-side:
    • Use skeletons during data fetches to maintain responsiveness.
    • Defer chart rendering until data is available to avoid unnecessary computations.
  • Server-side:
    • Persist analytics records to reduce repeated computation.
    • Batch queries for analytics by user or test to minimize database round-trips.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Charts not rendering:
    • Verify query keys and ensure backend endpoints are implemented.
    • Confirm theme context is applied for chart colors.
  • Missing analytics data:
    • Check storage operations for analytics retrieval by user or test.
    • Ensure analytics records are created after assessments.
  • AI analysis failures:
    • Validate input payload format for analyzeTestPerformance.
    • Inspect fallback logic for average score calculation.

Section sources

  • performance-chart.tsx
  • storage.ts
  • openai.ts

Conclusion

PersonalLearningPro’s result analysis and tracking system combines client-side dashboards with server-side analytics storage and AI insights. While several endpoints are currently disabled for demonstration, the architecture supports scalable aggregation, visualization, and reporting. Future enhancements can focus on implementing backend endpoints, expanding filtering/sorting, and adding export/share capabilities.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

  • Example analytics record fields:
    • userId, testId, weakTopics, strongTopics, recommendedResources, insightDate.

Section sources

  • schema.ts

Clone this wiki locally