KL Sync

An exhaustive, unofficial, minimalist ERP client for KL University.

---

🌐 Live Production Deployment

Access the live production instance deployed on Vercel: 👉 https://klhb.vercel.app

---

✨ Project Overview

KL University's official ERP system handles student data, including attendance, marks, timetables, and fee receipts. However, the legacy interface lacks modern mobile responsiveness and performance optimization.

KL Sync serves as a high-performance proxy and modern web client built with Next.js 16, React 19, and Tailwind CSS v4. User sessions are authenticated-encrypted server-side using AES-256-GCM without persisting user credentials in a database.

The HTML responses from the ERP are parsed intelligently via Cheerio and transformed into clean JSON payloads rendered onto a dark cyber minimalist dashboard following strict WCAG 2.2 AAA accessibility standards.

Detailed architectural blueprints can be found in ARCHITECTURE.md, and the design system specification is documented in DESIGN.md.

Note: This is an independent open-source project built by students. It is not endorsed by or affiliated with KL University. See the Disclaimer.

---

🏗️ Modular Scraper Architecture (src/lib/scrapers/)

The core scraper engine was recently refactored from a monolithic file into modular sub-scrapers under src/lib/scrapers/:

src/lib/
├── scraper.ts               # Barrel file / facade re-exporting all sub-scrapers
└── scrapers/
    ├── http-jar.ts          # Cookie jar management, fetch wrapper, timeout signal & table parsing
    ├── attendance.ts        # Captcha retrieval, authentication, and attendance data scraper
    ├── timetable.ts         # Timetable matrix scraper & heuristic matrix validator
    ├── marks.ts             # Internal marks, semester end exam results & CGPA scraper
    ├── fee.ts               # Fee receipts and generic module data proxy
    └── profile.ts           # Student profile and multi-tab demographics parser

Key Architectural Improvements

• Decoupled Responsibilities: Cookie jar handling and network logic live in http-jar.ts, isolating HTTP transport from page-specific Cheerio selector logic.
• Backward Compatibility: src/lib/scraper.ts functions as a facade, ensuring existing imports across API routes and components remain unaffected.
• Resilient Fetch Timeout: All HTTP calls wrap fetching with AbortSignal.timeout(25000) to ensure Next.js worker threads never hang indefinitely when university servers lag.

---

🔐 Configuration & Security

KL Sync uses environment variables to secure sessions and configure backend behaviors. Configure these in your .env.local file.

Variable	Requirement	Description
SESSION_SECRET	Strictly Required in Production	A 32+ character random secret string used to derive a fixed 32-byte key for AES-256-GCM session encryption. In production, omitting SESSION_SECRET triggers a fatal runtime exception ([SECURITY FATAL]).
CAP_SECRET	Required	Secret key for signing Cap CAPTCHA nonces and validating proof-of-work challenges.
UPSTASH_REDIS_REST_URL	Required	Upstash Redis REST endpoint URL for distributed nonce validation & token redemption (with built-in in-memory fallback for local dev).
UPSTASH_REDIS_REST_TOKEN	Required	Upstash Redis REST access token.
OCR_SPACE_API_KEY	Optional	API Key for OCR.space visual security code auto-solving (defaults to helloworld).
NODE_ENV	Optional	Set to development locally or production when deployed.

---

🚀 Local Development Setup

1. Clone the Repository

   git clone https://github.com/tejaswin-amara/kl-sync.git
   cd kl-sync

2. Install Dependencies

   npm install

3. Configure Environment Variables

   cp .env.example .env.local

   Add a secure SESSION_SECRET in .env.local.

4. Start Development Server

   npm run dev

   Access the dashboard at http://localhost:3000.

---

🛠️ Quality Gates & Verification Commands

To run all automated quality verification checks locally:

# 1. Run complete Unit & E2E Test Suite (219/219 Passing)
npm run test

# 2. Run Programmatic Agent-as-Judge AI Capability Test Suite (9/9 Passing)
npx tsx scripts/agent-as-judge.ts

# 3. Run strict TypeScript type-checking (0 Errors)
npx tsc --noEmit

# 4. Run ESLint static code analysis (0 Warnings/Errors)
npm run lint

# 5. Run Next.js production build verification
npm run build

---

⚖️ Disclaimer

KL Sync is an independent project built by a student, for KLU students. It has no affiliation with, endorsement from, or support from KL University. Your ERP credentials are used strictly to authenticate against the official ERP and are never saved or stored.

---

Built with ❤️ by Tejaswin for KLU students.