Skip to content

Test Assignment & Distribution

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

Test Assignment & Distribution

**Referenced Files in This Document** - [schema.ts](file://shared/schema.ts) - [mongo-schema.ts](file://shared/mongo-schema.ts) - [storage.ts](file://server/storage.ts) - [routes.ts](file://server/routes.ts) - [test-details-form.tsx](file://client/src/components/test/test-details-form.tsx) - [create-test.tsx](file://client/src/pages/create-test.tsx) - [recent-tests-table.tsx](file://client/src/components/dashboard/recent-tests-table.tsx) - [student-dashboard.tsx](file://client/src/pages/student-dashboard.tsx) - [analytics.tsx](file://client/src/pages/analytics.tsx) - [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

Introduction

This document describes the test assignment and distribution system in PersonalLearningPro. It covers how tests are created, scheduled, and distributed to students; how assignments are tracked and updated; how notifications and reminders are handled; and how administrators and teachers manage assignments at scale. It also documents analytics and reporting capabilities, role-based access control, and operational controls for bulk actions and conflict resolution.

Project Structure

The system spans three layers:

  • Shared domain models define typed schemas for tests, questions, attempts, answers, analytics, and assignments.
  • Server-side persistence and routing implement CRUD operations, access control, and assignment lifecycle management.
  • Client-side dashboards and forms provide user interfaces for creating tests, viewing assignments, and monitoring analytics.
graph TB
subgraph "Shared Layer"
SH_SCHEMA["shared/schema.ts"]
SH_MONGO["shared/mongo-schema.ts"]
end
subgraph "Server Layer"
SR_STORAGE["server/storage.ts"]
SR_ROUTES["server/routes.ts"]
end
subgraph "Client Layer"
CL_FORM["client/src/components/test/test-details-form.tsx"]
CL_CREATE["client/src/pages/create-test.tsx"]
CL_RECENT["client/src/components/dashboard/recent-tests-table.tsx"]
CL_STUDENT_DASH["client/src/pages/student-dashboard.tsx"]
CL_ANALYTICS["client/src/pages/analytics.tsx"]
end
SH_SCHEMA --> SH_MONGO
SH_MONGO --> SR_STORAGE
SR_STORAGE --> SR_ROUTES
SR_ROUTES --> CL_FORM
CL_FORM --> CL_CREATE
CL_CREATE --> SR_ROUTES
SR_ROUTES --> CL_RECENT
SR_ROUTES --> CL_STUDENT_DASH
SR_ROUTES --> CL_ANALYTICS
Loading

Diagram sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts
  • routes.ts
  • test-details-form.tsx
  • create-test.tsx
  • recent-tests-table.tsx
  • student-dashboard.tsx
  • analytics.tsx

Section sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts
  • routes.ts
  • test-details-form.tsx
  • create-test.tsx
  • recent-tests-table.tsx
  • student-dashboard.tsx
  • analytics.tsx

Core Components

  • Test model: Defines test metadata, scheduling, and status.
  • Question model: Defines question variants and scoring.
  • TestAttempt model: Tracks student attempts, timing, and status.
  • Answer model: Stores student responses and AI-assisted evaluation.
  • Analytics model: Aggregates learning insights per user/test.
  • TestAssignment model: Central entity for distributing tests to students, including due dates, status, and notification flags.

These models are validated by Zod schemas and persisted via Mongoose with auto-incremented numeric IDs and supporting indexes.

Section sources

  • schema.ts
  • mongo-schema.ts

Architecture Overview

The system enforces role-based access control at the route level and uses a storage abstraction to persist and query entities. The client interacts with server endpoints to create and manage tests, assign them to students, track attempts and answers, and view analytics.

sequenceDiagram
participant Client as "Client UI"
participant Routes as "Routes (/api/*)"
participant Storage as "Storage (MongoStorage)"
participant DB as "MongoDB"
Client->>Routes : POST /api/tests (teacher)
Routes->>Storage : createTest(testData)
Storage->>DB : insert Test
DB-->>Storage : Test
Storage-->>Routes : Test
Routes-->>Client : 201 Test
Client->>Routes : POST /api/test-attempts (student)
Routes->>Storage : createTestAttempt(attemptData)
Storage->>DB : insert TestAttempt
DB-->>Storage : TestAttempt
Storage-->>Routes : TestAttempt
Routes-->>Client : 201 TestAttempt
Loading

Diagram sources

  • routes.ts
  • storage.ts
  • routes.ts
  • storage.ts

Section sources

  • routes.ts
  • storage.ts
  • routes.ts
  • storage.ts

Detailed Component Analysis

Test Creation and Scheduling

  • Teachers create tests with title, subject, class, date, duration, total marks, and question types. The system validates inputs and persists the test with a draft/published status.
  • Students see tests filtered by their class and status, enabling discovery of upcoming assessments.
sequenceDiagram
participant Teacher as "Teacher UI"
participant Routes as "Routes (/api/tests)"
participant Storage as "Storage"
participant DB as "MongoDB"
Teacher->>Routes : POST /api/tests
Routes->>Storage : createTest(parsedTestData)
Storage->>DB : insert Test
DB-->>Storage : Test
Storage-->>Routes : Test
Routes-->>Teacher : 201 Test
Teacher->>Routes : GET /api/tests?status=published
Routes->>Storage : getTestsByClass(class)
Storage->>DB : find Tests by class
DB-->>Storage : Tests[]
Storage-->>Routes : Tests[]
Routes-->>Teacher : 200 Tests[]
Loading

Diagram sources

  • test-details-form.tsx
  • routes.ts
  • storage.ts

Section sources

  • test-details-form.tsx
  • routes.ts
  • storage.ts

Assignment Distribution Mechanisms

  • Assignments link a test to a specific student, recording who assigned it, when it was assigned, due date, initial status, and a flag indicating whether a notification was sent.
  • The system supports retrieving assignments by student, by test, and by combined filters. Updates allow changing status and other fields.
classDiagram
class TestAssignment {
+number id
+number testId
+number studentId
+number assignedBy
+date assignedDate
+date dueDate
+string status
+boolean notificationSent
}
class MongoTestAssignment {
+createTestAssignment(doc)
+getTestAssignment(id)
+getTestAssignments(filters)
+updateTestAssignment(id, update)
+getTestAssignmentsByTest(testId)
+getTestAssignmentByStudentAndTest(studentId, testId)
}
MongoTestAssignment --> TestAssignment : "persists"
Loading

Diagram sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts

Section sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts

Scheduling System: Availability, Deadlines, and Time Limits

  • Tests carry a scheduled date and duration. Attempts record start/end times and status, enabling time-bound delivery and completion tracking.
  • Status transitions support pending → started → completed, with overdue handling for late submissions.
flowchart TD
Start(["Create Test"]) --> Publish["Publish Test"]
Publish --> Available["Test Available to Students"]
Available --> Attempt["Student Starts Attempt"]
Attempt --> InProgress["Attempt in Progress"]
InProgress --> Submit{"Submitted?"}
Submit --> |Yes| Evaluate["Evaluate Answers"]
Submit --> |No| Timeout{"Exceeded Duration?"}
Timeout --> |Yes| MarkLate["Mark Overdue"]
Timeout --> |No| InProgress
Evaluate --> Completed["Completed"]
MarkLate --> Completed
Loading

Diagram sources

  • schema.ts
  • schema.ts
  • schema.ts

Section sources

  • schema.ts
  • schema.ts
  • schema.ts

Assignment Tracking, Completion Monitoring, and Rescheduling

  • Assignment status is tracked per student/test combination. The system supports querying by status and updating statuses (e.g., overdue).
  • Students can view upcoming tests and recent results on their dashboards, while analytics surfaces completion rates and performance metrics.
sequenceDiagram
participant Student as "Student UI"
participant Routes as "Routes"
participant Storage as "Storage"
participant DB as "MongoDB"
Student->>Routes : GET /api/tests
Routes->>Storage : getTestsByClass(user.class)
Storage->>DB : find Tests
DB-->>Storage : Tests[]
Storage-->>Routes : Tests[]
Routes-->>Student : Tests[]
Student->>Routes : GET /api/test-attempts?studentId=...
Routes->>Storage : getTestAttemptsByStudent(studentId)
Storage->>DB : find Attempts
DB-->>Storage : Attempts[]
Storage-->>Routes : Attempts[]
Routes-->>Student : Attempts[]
Loading

Diagram sources

  • routes.ts
  • storage.ts
  • student-dashboard.tsx

Section sources

  • routes.ts
  • storage.ts
  • student-dashboard.tsx

Notification Systems and Reminders

  • The assignment schema includes a notificationSent flag. While the backend does not implement a dedicated notification worker in the provided files, the presence of the flag indicates an extensibility point for integrating reminders or messaging systems.

Section sources

  • schema.ts
  • mongo-schema.ts

Role-Based Access Control and Visibility

  • Route handlers enforce role-based permissions:
    • Teachers can create/update tests and manage questions for their own tests.
    • Students can only access tests assigned to their class and can attempt published tests.
    • Access checks compare session roles and ownership/class membership against stored entities.
flowchart TD
A["Request Received"] --> B{"Authenticated?"}
B --> |No| E["401 Unauthorized"]
B --> |Yes| C{"Role Check"}
C --> |Teacher| D_Teacher["Allowed for owned resources"]
C --> |Student| D_Student["Allowed for class resources"]
C --> |Other| F["403 Forbidden"]
D_Teacher --> G["Proceed"]
D_Student --> G
Loading

Diagram sources

  • routes.ts
  • routes.ts
  • routes.ts

Section sources

  • routes.ts
  • routes.ts
  • routes.ts

Assignment Analytics, Participation Rates, and Completion Statistics

  • Analytics records per-user/per-test insights, enabling dashboards to compute completion rates and performance summaries.
  • The analytics page renders pie charts and summary cards for test completion and performance.
sequenceDiagram
participant Client as "Analytics UI"
participant Routes as "Routes"
participant Storage as "Storage"
participant DB as "MongoDB"
Client->>Routes : GET /api/analytics?userId=...
Routes->>Storage : getAnalyticsByUser(userId)
Storage->>DB : find Analytics
DB-->>Storage : Analytics[]
Storage-->>Routes : Analytics[]
Routes-->>Client : Analytics[]
Loading

Diagram sources

  • routes.ts
  • storage.ts
  • analytics.tsx

Section sources

  • routes.ts
  • storage.ts
  • analytics.tsx

Bulk Assignment Operations and Administrative Controls

  • The storage interface exposes methods to fetch assignments by test or student, enabling bulk operations such as rescheduling or mass notifications.
  • Administrative dashboards can leverage these APIs to manage large-scale distributions and monitor outcomes.
flowchart TD
Start(["Admin Action"]) --> Fetch["Fetch Assignments by Filters"]
Fetch --> Update["Update Status/Deadlines"]
Update --> Notify["Send Notifications (extensibility)"]
Notify --> Report["Generate Reports"]
Report --> End(["Done"])
Loading

Diagram sources

  • storage.ts
  • storage.ts
  • storage.ts

Section sources

  • storage.ts
  • storage.ts
  • storage.ts

Assignment Conflicts and Rescheduling Options

  • Conflict prevention: Students cannot start multiple in-progress attempts for the same test. The attempt creation endpoint rejects duplicates.
  • Rescheduling: Administrators and teachers can update test dates and deadlines via test update endpoints. Assignment due dates can be adjusted through assignment updates.
flowchart TD
A["Attempt Creation Request"] --> B["Load Existing Attempts"]
B --> C{"Any in-progress for same test?"}
C --> |Yes| D["Reject with 400"]
C --> |No| E["Create Attempt"]
Loading

Diagram sources

  • routes.ts
  • storage.ts

Section sources

  • routes.ts
  • storage.ts

Dependency Analysis

The following diagram maps core dependencies among shared models, storage, and routes.

graph LR
SH_SCHEMA["shared/schema.ts"] --> SR_STORAGE["server/storage.ts"]
SH_MONGO["shared/mongo-schema.ts"] --> SR_STORAGE
SR_STORAGE --> SR_ROUTES["server/routes.ts"]
SR_ROUTES --> CL_FORM["client/test-details-form.tsx"]
SR_ROUTES --> CL_CREATE["client/create-test.tsx"]
SR_ROUTES --> CL_RECENT["client/recent-tests-table.tsx"]
SR_ROUTES --> CL_STUDENT_DASH["client/student-dashboard.tsx"]
SR_ROUTES --> CL_ANALYTICS["client/analytics.tsx"]
Loading

Diagram sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts
  • routes.ts
  • test-details-form.tsx
  • create-test.tsx
  • recent-tests-table.tsx
  • student-dashboard.tsx
  • analytics.tsx

Section sources

  • schema.ts
  • mongo-schema.ts
  • storage.ts
  • routes.ts
  • test-details-form.tsx
  • create-test.tsx
  • recent-tests-table.tsx
  • student-dashboard.tsx
  • analytics.tsx

Performance Considerations

  • Indexes on assignment queries (studentId/status, testId, dueDate/status) improve filtering and reporting performance.
  • Using auto-increment counters ensures stable numeric IDs and simplifies joins.
  • Client-side caching via React Query can reduce redundant network requests for test lists and analytics.

[No sources needed since this section provides general guidance]

Troubleshooting Guide

  • Authentication failures: Ensure the session includes a valid userId and role; otherwise routes return 401/403.
  • Authorization failures: Teachers cannot modify others’ tests; students cannot access tests outside their class.
  • Attempt conflicts: If a student tries to start a second in-progress attempt for the same test, the request is rejected.
  • Validation errors: Zod-based validation returns structured 400 responses with error details.

Section sources

  • routes.ts
  • routes.ts
  • routes.ts

Conclusion

PersonalLearningPro’s test assignment and distribution system combines robust role-based access control, clear scheduling semantics, and flexible assignment tracking. The shared models and storage abstractions enable scalable bulk operations and analytics, while the client dashboards provide actionable insights for students and educators. Extending notification and reminder workflows is straightforward given the existing assignment schema and storage interfaces.

Clone this wiki locally