HMG Academy CBT Pro Feature & Deployment Guide
A detailed expert explanation of every major system feature and the exact deployment process for schools, tutors, academies, and virtual classrooms.
1. System Purpose
HMG Academy CBT Pro is a zero-build, static-web computer-based testing platform. It allows teachers to create exams, students to take exams by link or code, and administrators to supervise teacher accounts and platform-wide data. It deliberately avoids paid AI APIs. All advanced marking is done using transparent rule-based logic in the browser, while data storage uses the Supabase free tier.
2. Role-Based Portals
Landing Page
index.html explains the platform, shows supported exams, and routes users to Teacher, Student, and Admin portals.
Teacher Dashboard
Teachers create exams, upload/enter questions, manage rosters, view results, run analytics, export reports, and download backups.
Student Portal
Students enter via direct link or access code, verify identity if required, sit timed exams, and receive instant result review.
Admin Panel
Administrators approve/deactivate teachers, view platform KPIs, export platform CSV, and run security diagnostics without service-role exposure.
3. Teacher Features Explained
Exam Configuration
Teachers define subject, class, term, topic, exam type, session, pass mark, duration, attempt limit, question pull count, open/closed status, and optional scheduled close time.
Multiple Input Methods
Questions can be added through CSV, Excel/XLSX, text-based PDF extraction, manual typing, and JSON exam package import. SheetJS and PDF.js are free CDN tools.
Question Bank Editor
Existing exam questions can be previewed, edited, extended, deleted, exported as CSV, duplicated into new exams, and reused through package exports.
Sharing Tools
Every exam receives a six-character code and a direct student.html?code=XXXXXX link, plus WhatsApp share, printable access sheet, and copyable instructions.
Registered Students
Teachers can create or import class rosters. Registered-mode exams require the student to enter a matching Student ID before the start button is enabled.
Analytics & Reports
Teachers see score tables, score distribution charts, pass/fail ratio, trend chart, leaderboard, filtered insights, item analysis CSV, and general CSV export.
Enterprise Backup
Teachers can export exams, students, and result summaries as JSON. Student emergency result JSON files can be imported if network saving failed.
SQL Setup Assistant
The settings page includes copyable SQL blocks for RLS, result policies, student rosters, profiles, admin RPC functions, and diagnostic queries.
4. Student Features Explained
Link or Code Entry
Students may paste the full link or type only the access code. The parser accepts ?code=, ?exam=, hash values, and raw codes.
Integrity Pledge
Before starting, the student must accept an honesty pledge. This ensures rules are visible and creates a clear conduct expectation.
Timer & Navigation
Students get a countdown timer, warning colours near the end, question navigator, answer progress, jump-to-unanswered, and flag-for-review buttons.
Scientific Calculator
The built-in browser calculator supports trigonometry, logarithms, powers, constants, memory, and history without external paid services.
Anti-Cheat Logging
The portal logs tab switching, blur events, right-click, copy/paste attempts, print/source/devtools shortcuts, fullscreen exits, and screenshot key attempts.
Optional Proctoring
Camera intake photos, periodic snapshots, optional face checks, and audio spike detection use browser APIs and free open-source face-api.js. No paid AI API is used.
Instant Result Review
Students see score, grade, pass/fail status, time used, integrity summary, explanations, and question-by-question feedback immediately after submission.
Emergency Backup
If saving fails because of network/database issues, students can download a backup JSON file and send it to the teacher for later import.
5. Supported Question Types
| Type | Code | How It Works | Scoring |
|---|---|---|---|
| Multiple Choice | mcq | Choose one option A-D. | 1 or 0. |
| True / False | tf | Choose True or False labels. | 1 or 0. |
| Multiple Response | mrq | Select all correct options. | Partial credit or all-or-nothing. |
| Short Answer | short | Type a word or phrase. | Case-insensitive exact/alternate match. |
| Numeric | numeric | Type a number. | Accepted within teacher tolerance. |
| Matching | matching | Pair left and right items. | Partial credit per pair. |
| Ordering | ordering | Arrange items in correct sequence. | Partial credit per position. |
| Cloze | cloze | Fill multiple blanks. | Partial credit per blank. |
| Essay / Keyword | essay | Write a longer answer. | Rule-based keywords/minimum words; teacher review recommended. |
| Categorization | categorization | Assign each item to a category. | Partial credit per item. |
| Multi-Part Numeric | multi_numeric | Answer several numeric parts. | Partial credit per numeric part. |
6. Why No AI API Is Used
Paid AI APIs are not cost-effective for a free school CBT platform. This system therefore uses deterministic, explainable rules: exact matching, accepted-answer lists, numeric tolerance, partial-credit rubrics, keyword checks, and teacher review. This keeps running costs near zero and avoids unpredictable API billing.
7. Free Tools Used
HTML/CSS/Vanilla JSSupabase Free TierGitHub PagesCloudflare PagesVercelChart.jsSheetJSPDF.jsface-api.jsWeb Audio APIService Worker
8. Clear Deployment Process
Prepare Supabase
Create a Supabase project on the free tier. Copy the Project URL and anon public key. Do not copy or expose the service_role key.
Confirm Configuration
Open teacher.html, student.html, and admin.html. Confirm SB_URL and SB_KEY match your Supabase project.
Upload Static Files
Upload the entire folder, including assets/, manifest.webmanifest, hmg-icon.svg, sw.js, offline.html, and all HTML files to GitHub Pages, Cloudflare Pages, or Vercel.
Set Auth Redirect URLs
In Supabase: Authentication → URL Configuration. Add your deployed site URL and likely callback URLs, for example https://your-domain/teacher.html and https://your-domain/admin.html.
Run SQL Setup
Open the deployed teacher.html, log in, go to Settings, and run every SQL block in Supabase SQL Editor. This creates RLS policies, students table, profiles, result columns, and admin RPC functions.
Create Admin Profile
Use the configured admin email or set profiles.is_admin=true / role='admin' for your admin account. Then test admin.html.
Run Validators
Open deployment_validator.html to check static assets. In Teacher Settings, click Live Diagnostic. In Admin Panel, check Security diagnostics and download the SQL smoke test if needed.
Functional Test
Create a sample exam, open it, copy the link/code, take it as a student, submit, confirm result appears in Teacher Dashboard, export CSV, and view per-question answers.
Go Live
Approve teachers, create real rosters, publish exams, share codes/links, and schedule routine backups. Store backup JSONs securely.
9. Security Notes
- The Supabase anon key is public by design. Security depends on RLS policies.
- Never place Supabase service_role keys in frontend HTML or JavaScript.
- Use HTTPS hosting for camera, microphone, PWA, and authentication reliability.
- Client-side proctoring is evidence/support, not a replacement for school policy.
- Treat result exports, proctor photos, and backup JSON files as confidential student records.