Examination, Assessment & Report Cards
The academic evaluation pipeline: ExamSchedule → StudentMark → ReportCard. Covers exam scheduling, marks entry with automatic grading, weighted report card generation (including a live-rendered PDF and a pull of Chapter 10 attendance data), exam analytics, and a promotion / re-evaluation workflow that is fully built on the backend today.
Exam Data Flow
Basic Tier Features
BasicExam Scheduling
- ExamSchedule model: title, course, examType (unit_test/mid_term/final/practical/oral/project), term, academicYear, scheduledDate
- maxMarks defaults to 100, passMarks defaults to 35, weightage defaults to 100 — all overridable per exam
- Configurable gradeThresholds (A+/A/B/C/D boundaries) drive automatic grade computation
- Editing or deleting a schedule is blocked once any marks have been entered against it
- isPublished gate controls student/parent visibility of the schedule
- Admin UI: /dashboard/admin/grades/exams, /dashboard/admin/grades/exams/create
Marks Entry
- StudentMark model, unique per (examSchedule, student) — upserted, never duplicated
- Bulk entry endpoint accepts an array of { studentId, marksObtained, isAbsent, remarks } in one request
- Absent students get marksObtained: null, grade: "AB", isPassing: false
- Grade computed against the parent exam's gradeThresholds at entry time and on every update
- Teacher UI: /dashboard/teacher/grades, /dashboard/teacher/grades/[examId] — marks entry grid
Report Card Generation
- Aggregates every StudentMark for a term/academicYear per student, grouped by subject (course)
- Applies each exam's weightage to compute per-subject percentage, final grade, and pass/fail
- Pulls the student's attendance percentage for the term's date range from Chapter 10's DailyAttendance data
- Class is dense-ranked by overallPercentage within the same generation batch (rank + classSize stored on each card)
- Admin can add principalRemarks and per-subject teacherRemarks before publishing
- Report card PDF is rendered synchronously with pdfkit and streamed to the client — not a background job
- Admin UI: /dashboard/admin/grades/report-cards · Student UI: /dashboard/student/grades/report-card/[id]
Exam & Report Card Analytics
- Subject-wise, class-wise, and school-wide performance analytics
- Individual student performance trend across exams
- Class/section/school ranking tables
- Admin UI: /dashboard/admin/grades/analytics — 4-panel dashboard (subject, class, school, ranking)
Promotion Management
- Evaluates every student against their published annual report card: any failed subject, or attendance % below a configurable minimum (default 75%), flags them
- Admin records a promote or detain decision per student; promotion delegates to the Chapter 6 Student Lifecycle promotion recorder (class/section/academic-year change)
- Every decision is written to AuditLog and surfaced via a promotion report endpoint
- Student/parent read-only endpoint for own promotion history
- API-only today — no dedicated web/mobile promotion UI has been built yet
Re-evaluation Requests
- Student or linked parent requests re-evaluation of a specific StudentMark with a reason; one request per mark (unique constraint)
- Admin reviews and approves or rejects
- Once approved, a different teacher re-enters the mark via the normal marks-update endpoint, then the request is marked completed with before/after marks recorded
- Every completion is audit-logged
- API-only today — no dedicated web/mobile re-evaluation UI has been built yet
Result Publication
- Exam schedules and report cards each carry their own isPublished / publishedAt gate
- Students only ever see published exam schedules and their own published report cards
- Parents see a published report card only for a linked child
- Parent UI: /dashboard/parent/exams
Planned — Not Yet Implemented
Not Yet Implemented
- Excel/CSV bulk import of marks — current bulk endpoint accepts a JSON array from the marks-entry grid, not a spreadsheet upload
- Automatic multi-channel (WhatsApp/push/email) notifications on result and report-card publication — publishing today only flips the isPublished flag
- GPA scale computation (4/5/10-point) — grade computation currently only supports letter grades (A+ through F) via configurable percentage thresholds
- Merit lists / top-performer certificates generation
- Dedicated admin/teacher UI for reviewing promotion decisions and re-evaluation requests (both workflows are API-complete but UI-less)
API Reference — Chapter 12
Exam Schedules & Marks
/api/grades/examsCreate an exam schedule (admin)
/api/grades/examsList exam schedules — teachers see only their own courses' exams
/api/grades/exams/:idGet a single exam schedule
/api/grades/exams/:idUpdate a schedule — blocked once marks exist
/api/grades/exams/:idDelete a schedule — blocked once marks exist
/api/grades/exams/:id/publishPublish the exam schedule to students
/api/grades/exams/:id/marksBulk enter/update marks for an exam
/api/grades/exams/:id/marksList all marks for an exam
/api/grades/exams/:id/marks/:sidUpdate a single student's mark
Student & Parent Marks View
/api/grades/my-marksStudent's own marks — published exams only
/api/grades/student/:studentId/marksParent/admin view of a student's marks
Report Cards
/api/grades/report-cards/generateGenerate/refresh report cards for a term + academicYear
/api/grades/report-cardsList report cards (admin)
/api/grades/report-cards/myStudent's own published report cards
/api/grades/report-cards/student/:sidParent/admin view of a student's report cards
/api/grades/report-cards/:idGet a single report card
/api/grades/report-cards/:id/remarksAdmin adds remarks (admin only)
/api/grades/report-cards/:id/publishPublish a report card
/api/grades/report-cards/:id/downloadStream the report card as a PDF (pdfkit)
Analytics
/api/analytics/exam/subjectSubject-wise performance analytics
/api/analytics/exam/classClass-level analytics (avg, pass rate, distribution)
/api/analytics/exam/schoolSchool-wide result analytics
/api/analytics/exam/student/:idIndividual student performance trend
/api/analytics/exam/rankingClass, section, school ranking tables
Promotion
/api/promotions/evaluateEvaluate promotion eligibility for a class/section/year
/api/promotions/approveRecord promote/detain decisions in bulk
/api/promotions/reportPromotion decision audit report
/api/promotions/my/:studentIdStudent/parent read-only promotion history
Re-evaluation
/api/re-evaluationStudent/parent requests re-evaluation of a mark
/api/re-evaluationAdmin review queue
/api/re-evaluation/myRequester's own re-evaluation requests
/api/re-evaluation/:id/reviewApprove or reject a request
/api/re-evaluation/:id/completeMark a request completed after the mark is re-entered
Frontend Pages
| Path | Role | Description | Tier |
|---|---|---|---|
| /dashboard/admin/grades/exams | Admin | Exam schedule list | Basic |
| /dashboard/admin/grades/exams/create | Admin | Create an exam schedule | Basic |
| /dashboard/admin/grades/report-cards | Admin | Generate, review, and publish report cards | Basic |
| /dashboard/admin/grades/analytics | Admin | Subject / class / school analytics + ranking | Basic |
| /dashboard/teacher/grades | Teacher | Exams assigned to the teacher's courses | Basic |
| /dashboard/teacher/grades/[examId] | Teacher | Marks entry grid for an exam | Basic |
| /dashboard/student/grades | Student | Published marks across exams | Basic |
| /dashboard/student/grades/report-card/[id] | Student | Individual published report card view | Basic |
| /dashboard/parent/exams | Parent | Child's exam schedules and published results | Basic |
Mobile Screens
(student)/exams.tsx(student)/report-card.tsx(parent)/exams.tsx(parent)/report-card.tsx(parent)/reports.tsxNo teacher-facing mobile screen exists yet for marks entry — teachers enter marks via the web marks-entry grid only.