a
Scope
Tree-Structured Course Authoring
Four-level content hierarchy: Category ? Subject ? Topic ? Question. Admin and Teacher can build, edit and navigate content via an interactive collapsible tree with inline action controls.
Teacher ? Admin Approval Workflow
Teachers create content in DRAFT, submit for PENDING review. Admin approves or rejects with a reason. Rejected content shows a feedback banner so teachers can correct and resubmit.
Assessment Engine
Build exams from approved question banks. Seven question types: MCQ Single, MCQ Multiple, True/False, Short Answer, Essay, Code, and Image-Based. Timed student attempts with auto-save and auto-marking.
Exam Scheduling & Calendar
Schedule exams for classes on a drag-and-drop calendar grid. Supports single events, date ranges, and recurring schedules. Teachers see only their assigned events; admins see all.
Student Portal
Students log in, undergo a forced password change on first access, then view a personalised dashboard with active exams, upcoming schedules, recent results, and announcements from admin.
Reporting & Analytics
Class performance reports, teacher activity tracking, per-question analytics (flag/unflag), topic-level score breakdowns per student, revenue views, and exportable data to XLSX and PDF.
Communications & Notifications
In-app notification bell for all roles — triggered on approval actions, exam scheduling, marking completion. Pinned announcement board with audience targeting (Admin / Teacher / Student / All).
Audit Log & Platform Settings
Immutable JSONB audit log of all significant actions across the platform. Configurable platform settings with cache support. Bulk import via CSV and Excel, with question bank and exam paper PDF exports.
Content Hierarchy
Category — e.g. Year 10
Subject — e.g. English Language
Topic — e.g. Non-Fiction & Creative Writing
Question — MCQ, Essay, Code, Image-Based…
Approval Workflow
Draft
Teacher creates
›
Pending
Teacher submits
›
Approved
Admin approves ? visible to students
?
Rejected
Admin rejects with reason ? teacher corrects
? Admin-created content is auto-approved · ? Teacher edits to approved content re-trigger pending · ? Admin-owned nodes are read-only for teachers
b
Features & Functionality
| Module / Phase | Key Functionality | Highlights | Status |
|---|---|---|---|
| Authentication | JWT login for Admin, Teacher, Student; role-based route guards | Spring Security; forced password change for new students; sessionStorage JWT lifecycle | Done |
| Course Authoring (Base) | Full CRUD for Category ? Subject ? Topic ? Question across all roles | Interactive tree sidebar with expand/collapse; pending badges; soft delete on all nodes | Done |
| 7 Question Types | MCQ Single, MCQ Multiple, True/False, Short Answer, Essay, Code, Image-Based | Type-specific fields rendered dynamically; partial marking on MCQ Multiple; answer explanation capture | Done |
| Approval Workflow | Draft ? Submit ? Pending ? Approve / Reject with reason | Rejection banner in teacher UI; approval log table; auto-approve for admin content | Done |
| Phase 1 — Org Settings | Organisation branding, legal, address, contacts, academic config; logo upload | Topbar with user pill + notification bell; singleton org settings record | Done |
| Phase 2 — Teacher Workspace | Profile edit, avatar upload, password change; submission history with filters | Paginated submissions tracker; summary chips per status; rejection feedback in course UI | Done |
| Phase 3 — Assessment Engine | Exam builder, class management, student registration (+ CSV bulk import), exam scheduling | Timed student attempts with auto-save; auto-marking for objective types; manual marking queue for subjective | Done |
| Drag-Drop Calendar | Visual calendar grid for scheduling — single, date range, and recurring events | Teacher-assigned event filtering; series move dialog (THIS / THIS_AND_FORWARD / ALL); right-click context menu | Done |
| Student Portal | Student login, forced password change, dashboard with exam cards, results, announcements | Active / Upcoming / Completed exam tabs; teal role branding; must_change_password flag in DB | Done |
| Phase 4 — Reporting | Class reports, teacher activity reports, per-question analytics, student topic breakdowns | DB views for attempt_topic_scores + question_analytics; flag/unflag questions; XLSX + PDF export | Phase 4 |
| Phase 5 — Communications | In-app notifications (approval, exam, marking events); announcement board with priority + audience | Notification bell wired across all dashboards; dismissable pinned banner; AnnouncementPriority enum | Phase 5 |
| Phase 6 — Audit & Operations | Immutable JSONB audit log; bulk CSV/Excel import; platform settings with cache; question bank export | AuditLog with AuditAction enum; poi-ooxml + openpdf libraries; @Cacheable settings; exam paper PDF | Phase 6 |
Build Phases
Phase 1 ?
Org Settings & Notifications
Topbar, user menu, notification bell, organisation branding and legal settings
Phase 2 ?
Teacher Workspace
Profile management, avatar upload, submission history tracker with status filters
Phase 3 ?
Assessment Engine
Exam builder, class & student management, scheduling, attempts, auto and manual marking
Phase 4
Reporting & Analytics
Class reports, teacher activity, question analytics, topic breakdowns, export to XLSX/PDF
Phase 5
Communications
Full in-app notification system and announcement board with audience targeting
Phase 6
Audit, Import & Operations
Immutable audit log, bulk CSV/Excel import, platform settings, data exports
c
Pictorial Process Flow
?
Author Content
Teacher/Admin builds course tree
?
Approve
Admin reviews & approves content
?
Build & Schedule Exam
Select questions, set class & date
?
Student Attempts
Timed exam with auto-save
?
Mark & Score
Auto + manual marking queue
Analyse & Report
Results, topic scores, exports
1
Admin / Teacher — Build Course Content
Login with JWT. Navigate to Courses. Use the interactive tree to add Categories, Subjects, Topics, and Questions. Teachers save as DRAFT; admin content is auto-approved. Seven question types each render their own dynamic fields.
2
Teacher — Submit for Approval
Teacher clicks Submit ? status moves to PENDING. Admin sees the item in the Pending Approvals queue. If rejected (with a reason), a banner appears in the teacher's course UI so they can correct and resubmit.
3
Admin — Register Students & Create Classes
Admin creates student accounts (admin-set temp password forces change on first login). Students are assigned to one or more classes. Bulk CSV import available for large cohorts.
4
Admin / Teacher — Build Exam & Schedule
Select approved questions from the question bank, set marks and order. Submit exam for approval. Once approved, schedule it for a class via the drag-and-drop calendar. Single events, date ranges, or recurring series all supported.
5
Student — Attempt Exam
Student logs in ? forced password change on first access ? personalised dashboard shows upcoming exams. Student starts the attempt, answers questions (auto-saved), and submits. Timer enforced throughout.
6
Auto-Marking & Manual Marking Queue
On submission, AutoMarkingService scores MCQ, True/False, and Image-Based (MCQ path) questions instantly. Short Answer, Essay, and Code answers appear in the teacher/admin marking queue for manual review and scoring.
7
Results, Analytics & Reporting
Students see their results with topic-level score breakdowns. Admin and teachers access class reports, teacher activity dashboards, and per-question analytics. All data exportable to XLSX and PDF. Full audit log tracks every significant action.
d
Data Flow Diagram
Inputs
Admin / Teacher / Student Login (JWT)
Course Content (Category / Subject / Topic)
Questions (7 types + options + answers)
Approval Actions (approve / reject + reason)
Exam Config (questions, marks, order)
Class & Schedule Data
Student Registrations (+ CSV bulk import)
Exam Attempts (answers, auto-saved)
Manual Marking Scores
Organisation Settings + Logo
Platform Settings & Announcements
EduLearn API
Spring Boot · JPA · PostgreSQL
? JWT Auth + Role Guards
? Content Approval Service
? Auto-Marking Service
? Marking Queue Service
? Notification Service
? Audit Log Service
? UUID PKs · Soft Delete
? Paginated REST API (v1)
? Content Approval Service
? Auto-Marking Service
? Marking Queue Service
? Notification Service
? Audit Log Service
? UUID PKs · Soft Delete
? Paginated REST API (v1)
Outputs
Admin Dashboard KPIs & Pending Queue
Teacher Submission Status & Feedback
Approved Course Tree (student-visible)
Exam Builder (ordered question list)
Calendar Events (single / range / recurring)
Student Exam Interface (timed + auto-save)
Auto-Marked Scores
Marking Queue (subjective answers)
Student Results + Topic Breakdowns
Class & Teacher Reports
XLSX / PDF Exports + Audit CSV
Entity Relationship Summary
User (Admin/Teacher/Student) ? all content is linked via created_by, updated_by, approved_by
Category ? Subject (1:N) ? Topic (1:N) ? Question (1:N) + QuestionOption (1:N)
ApprovalLog records every APPROVED / REJECTED transition across all content levels
Exam ? ExamQuestion (ordered, 1:N) ? Question
Classroom ? StudentClass (M:N with User/Student) ? ExamSchedule (1:N, with series support)
ExamAttempt ? AttemptAnswer (1:N per question) — auto-marked on submit
Notification · Announcement · AuditLog (immutable JSONB) — all linked to User
All tables: UUID PKs · is_deleted + deleted_at soft-delete · created_at / updated_at auto-maintained
Category ? Subject (1:N) ? Topic (1:N) ? Question (1:N) + QuestionOption (1:N)
ApprovalLog records every APPROVED / REJECTED transition across all content levels
Exam ? ExamQuestion (ordered, 1:N) ? Question
Classroom ? StudentClass (M:N with User/Student) ? ExamSchedule (1:N, with series support)
ExamAttempt ? AttemptAnswer (1:N per question) — auto-marked on submit
Notification · Announcement · AuditLog (immutable JSONB) — all linked to User
All tables: UUID PKs · is_deleted + deleted_at soft-delete · created_at / updated_at auto-maintained
e
Technology Stack
Backend
Spring Boot
Web MVC, Data JPA, Security — full auto-configuration; build target: fat JAR
v3.2.5
Language
Java 17
Records, sealed types; Lombok for boilerplate reduction throughout
Java 17 LTS
ORM
Spring Data JPA + Hibernate
Hibernate 6.4; @SQLDelete + @Where for soft delete; @JdbcTypeCode for PG enums
Hibernate 6.4
Auth
Spring Security + JWT
OncePerRequestFilter auth filter; jjwt 0.12.3 (api + impl + jackson); @PreAuthorize on controllers
jjwt 0.12.3
Database
PostgreSQL
Native enums; gen_random_uuid() for all PKs; ddl-auto=none, schema managed via SQL init scripts
PG 15 · Docker
Frontend
Vanilla HTML5 / CSS3 / JS
No React or Vue — served directly from Spring Boot static resources; SPA-style page routing
Static · ES6
API
RESTful JSON API
Versioned at /api/v1/; standard response wrapper {status, message, data, pagination}; paginated endpoints
v1 · Paginated
Containerisation
Docker
PostgreSQL runs in Docker (port 5433); docker-compose.yml provided; Spring Boot runs natively
docker-compose
Build
Maven
System mvn (no wrapper); spring-boot-starter-parent; fat JAR packaging
mvn 3.x
Export (Phase 6)
Apache POI + OpenPDF
poi-ooxml 5.2.5 for XLSX export; openpdf 1.3.43 for exam paper and results PDF generation
POI · OpenPDF
Import (Phase 6)
OpenCSV
opencsv 5.9 for student bulk import via CSV; Excel import handled by POI parser
opencsv 5.9
Caching (Phase 6)
Spring Cache
@Cacheable on platform settings for low-latency config reads across the application
@Cacheable