PhilNITS Lab — Enterprise Exam Prep & OMR Grading Portal

An enterprise-grade exam preparation platform for the Philippine National Information Technology Standards (PhilNITS / ITPEC) FE and IP examinations. Features automatic Optical Mark Reader (OMR) paper grading, real-time interactive mock exams, topic calibration, and performance analytics.

---

Key Features

• Interactive Mock Exam Engine: Complete past-year examination papers under real exam conditions with timer controls, topic filtering, confidence marking, and instant feedback.
• Computer Vision OMR Paper Grading: Upload a photo of your printed A4 answer sheet. The custom C++ image engine performs perspective homography deskewing, BFS corner registration mark detection, and bubble darkness evaluation to grade paper sheets in seconds.
• Performance Analytics Dashboard: Track historical scores, topic breakdown radar/bar charts, weakness areas, and calibration stats.
• Authentication & Guest Offline Mode: Seamless GitHub OAuth authentication backed by Supabase with full offline/guest mode stubs for instant evaluation without logging in.
• Serverless Production Hardened: Fully optimized for deployment on Netlify Functions (AWS Lambda) with zero filesystem dependencies and fallback credentials.

---

Technology Stack

• Framework: Nuxt 4 (Vue 3 Composition API + TypeScript 6)
• Server Engine: Nitro Engine (Netlify Preset)
• Styling & UI: Tailwind CSS v4 + Nuxt UI
• Image Processing: Sharp C++ Engine (Cross-platform Linux x64 + WASM)
• Database & Auth: Supabase (PostgreSQL + Row-Level Security)
• State Management: Pinia + @vueuse/core

---

How to Add New Exam Papers & Documents

Follow these 3 easy steps to add new examination papers to PhilNITS Lab:

Step 1: Create the Exam JSON Answer Key (data/exams/)

Create a new .json file inside data/exams/ matching your exam ID (e.g., data/exams/IP-2026A-October.json):

{
  "pdf_filename": "2026A_IP_Questions.pdf",
  "exam_title": "ITPEC IP Exam, October 2026",
  "type": "IP",
  "year": "2026",
  "month": "October",
  "questions": 100,
  "time_limit": 120,
  "answers": {
    "1": "C",
    "2": "D",
    "3": "A",
    "4": "B"
  }
}

Step 2: Add the Official PDF Booklet (public/pdfs/)

Place the official examination question booklet PDF in public/pdfs/ matching the "pdf_filename" declared in Step 1:

public/pdfs/2026A_IP_Questions.pdf

Step 3: Register the Exam in exam-registry.ts

Open server/utils/exam-registry.ts and add 2 lines:

// 1. Add import statement at top of file
import ip2026a from '~~/data/exams/IP-2026A-October.json'

// 2. Add key-value pair to RAW_EXAMS map
const RAW_EXAMS: Record<string, any> = {
  ...
  'IP-2026A-October': ip2026a
}

That's it! Your new exam paper will instantly appear on the Practice Exams index page and will be fully supported in both interactive online mode and OMR paper grading mode!

---

Environment Setup & Local Development

Prerequisites

• Node.js: v22.0.0 or higher
• npm: v10.0.0 or higher

Local Installation

1. Clone the Repository:

   git clone https://github.com/HanazonoArchive/PhilNITSLab.git
   cd PhilNITSLab

2. Install Dependencies:

   npm install

3. Configure Environment Variables: Create a .env file in the root directory:

   NUXT_PUBLIC_SITE_URL="http://localhost:3000"
   NUXT_PUBLIC_SUPABASE_URL="https://irzilwmxunkcnajslbsi.supabase.co"
   NUXT_PUBLIC_SUPABASE_ANON_KEY="your-supabase-anon-key"

4. Start Development Server:

   npm run dev

   Open http://localhost:3000 in your browser.

📜 License

Distributed under the MIT License. See LICENSE for more information.