Electify – Smart University Elective Registration System

Electify is a high-performance, secure full-stack university elective registration and cohort management system. It guarantees a 100% fair, zero-waitlist, first-come, first-served course selection process powered by atomic PostgreSQL transaction row-locking safeguards, optional real-time seat updates via Supabase Realtime, and an Academic Year Server isolation workflow.

---

⚡ Key Highlights & Core Capabilities

• Atomic Concurrency Guarantee: PostgreSQL row-locking transactions handle simultaneous submissions with zero overbooking and automatic instant seat release on resubmission.
• Academic Year Timeline (Year Server) Isolation: Dedicated year selection screen after staff login (/faculty/session-select), organizing operations by academic timelines (e.g. 2025, 2026, 2027) with complete workspace isolation.
• Root Administrator Immutability: Multi-layer security protections guaranteeing the permanent Root Administrator ([email protected]) cannot be deleted, deactivated, or demoted.
• Single-Session Sentinel: Anti-sniping protection ensuring that logging in from another device immediately revokes any prior active sessions.
• Multi-Programme Tutor Supervision: Class tutors can claim and manage sections across multiple programmes and batches with strict student roster segregation.
• Subject Explorer & Preview Mode: Students can explore subject descriptions, syllabi, and prerequisites prior to window opening without locking seats.
• Live Event Monitor & Surveillance: Real-time staff monitoring feed, live seat metrics, and unregistered cohort tracking.
• Audit Logging & Receipts: A uniquely numbered receipt (ELC-<year>-<ODD|EVEN>-<seq>) and PDF are issued only when the student finalizes their registration (or when the window closes), plus an audit log, a registration replay, and PDF exports.

---

🚀 Tech Stack & Architecture

• Frontend: Next.js 16 (App Router, Server Components & Server Actions)
• UI & Components: React 19, shadcn/ui, Lucide Icons
• Styling: Tailwind CSS v4 (CSS-first design tokens)
• Database & Pooling: PostgreSQL 16 (via local instance, Neon, or Supabase connection pooling)
• ORM & Migrations: Drizzle ORM & Drizzle Kit
• Realtime Sync (optional): Supabase Realtime channels; disabled automatically when the Supabase URL/key are empty
• Auth & Session Security: Custom HMAC-signed JWT cookies, routing proxy (src/proxy.ts), and Bcryptjs password hashing (cost factor 12)
• Brute Force Protection: Database-backed login attempt tracking and automatic rate-limiting lockout
• Export Engine: Client-side high-fidelity PDF reporting using jsPDF & AutoTable

---

📂 Project Directory Structure

electify/
├── .github/                # CI/CD Workflows (GitHub Actions)
├── docs/                   # System Architecture, Database & Deployment Guides
│   ├── architecture/       # System design & folder structure documentation
│   ├── development/        # Code standards & testing workflows
│   ├── decisions/          # Architecture Decision Records (ADRs)
│   └── qa/                 # QA regression and test reports
├── drizzle/                # Database migrations generated by Drizzle Kit
├── public/                 # Static branding, presentation, and public assets
├── scripts/                # Database maintenance & mock data cleanup scripts
├── src/
│   ├── app/                # Next.js App Router Pages and Server Actions
│   │   ├── actions/        # Mutating server actions (admin, auth, tutor, register)
│   │   ├── api/            # API Route Handlers (health, switch-section)
│   │   ├── countdown/      # Pre-registration countdown waiting hall
│   │   ├── dashboard/      # Student registration portal & elective picker
│   │   ├── faculty/        # Staff & Administrative Control Panel
│   │   ├── login/          # Unified staff and student login portal
│   │   ├── maintenance/    # Global emergency maintenance redirect
│   │   ├── globals.css     # Design tokens and Tailwind CSS rules
│   │   └── layout.tsx      # Root application layout
│   ├── components/         # Reusable UI elements, modals, badges, data tables
│   ├── hooks/              # Custom reusable React hooks (e.g. useServerClock)
│   ├── lib/                # Shared utilities, database client, and security
│   │   ├── db/             # Drizzle client, unified schema, and seed scripts
│   │   ├── auth.ts         # JWT signing, validation, and session guard rules
│   │   ├── cache.ts        # Typed Next.js cache and route revalidation helpers
│   │   ├── password-policy.ts # Centralized password validation rules
│   │   ├── seat-ops.ts     # ACID row-locking seat operations
│   │   ├── seats.ts        # Pure seat display logic and thresholds
│   │   └── workspace.ts    # Academic workspace resolution and security
│   ├── types/              # Centralized domain and API TypeScript contracts
│   │   ├── academic.ts     # Hierarchy entities (faculties, depts, programmes)
│   │   ├── api.ts          # API response and health check contracts
│   │   ├── registration.ts # Registration and seat availability types
│   │   └── session.ts      # Authentication session and login types
│   └── proxy.ts            # Next.js 16 proxy: route protection & session validation
├── tests/                  # Automated test suites (unit, integration, and e2e)
├── drizzle.config.ts       # Drizzle Kit configuration file
├── next.config.ts          # Next.js configuration
└── package.json            # Dependencies and npm scripts

---

🗄️ Database Architecture (Drizzle ORM)

The relational schema is defined in src/lib/db/schema.ts:

Entity	Description
faculties	SRM Master Faculties (Engineering, Management, Science & Humanities, etc.)
departments	Academic departments tied to parent faculties (e.g., Computing Technologies)
programmes	Degree programs (MCA, B.Tech CSE, M.Tech, etc.) with level (UG/PG) and semesters
academic_batches	Cohort batches tied to programmes and graduation years
sections	Cohort subdivisions (Section A, B, C, etc.)
users	Unified user store for Students, Tutors, Coordinators, and System Admins
tutor_sections	Multi-class mapping table assigning tutors to specific cohort sections
registration_events	Registration windows and timelines (DRAFT, PUBLISHED, OPEN, CLOSED)
elective_groups	Elective buckets (e.g., Professional Elective I) with selection constraints
electives	Courses offering seat quotas (maxSeats, availableSeats, isFull)
registrations	Official student registration master receipts
student_registrations	Atomic elective course allocations mapped to confirmed registrations
replay_events	Real-time audit log of student course choices and seat modifications

---

🔑 User Roles & Permissions Matrix

Feature / Action	Student	Class Tutor	Course Coordinator	System Admin
Access Countdown Waiting Room	✅	❌	❌	❌
Select & Confirm Electives	✅	❌	❌	❌
Browse Subject Explorer Preview	✅	❌	❌	❌
Switch Academic Year Server	❌	✅	✅	✅
Manage Assigned Class Rosters	❌	✅	❌	❌
Unlock / Reset Student Submissions	❌	✅	✅	❌
Create & Schedule Registration Events	❌	❌	✅	✅
Configure Electives & Quotas	❌	❌	✅	✅
Import Students via CSV	❌	✅ (Class)	✅ (Batch)	✅
Export Enrollment Records (PDF)	❌	✅ (Class)	✅ (Batch)	✅
Manage Role-Based Staff Invites

---

🔒 Master Credentials & Authentication

1. Root Administrator

• Email: [email protected]
• Default Password: Configured via INITIAL_ADMIN_PASSWORD (or bootstrap setup)
• Role: SYSTEM_ADMIN
• Protection: Permanently protected as immutable Root Admin; cannot be deleted, deactivated, or demoted.

2. Faculty / Staff Portal

• Onboarding: Staff sign up via single-use, role-based invite codes created by the Root Admin.
• Workflow: Upon logging in, staff choose an active Academic Year Server timeline before accessing class rosters or event settings.

3. Student Portal

• Login ID: University register number (e.g. RA2532241010001); e-mail addresses are not accepted on the student form
• Onboarding: Students join their class with a tutor-issued signup code and choose their own password. Accounts created by a tutor start with a temporary credential and must set a new password at first sign-in.
• Password Policy: Minimum 8 characters, requiring at least one letter and one number, blocking trivial defaults.

---

🛠️ Local Development & Setup

On Windows? Follow WINDOWS_SETUP.md, a complete step-by-step guide for Windows 10/11 with PowerShell commands and troubleshooting.

Prerequisites

• Node.js: v20.9 or newer (required by Next.js 16); v24 LTS recommended (see .nvmrc). npm test needs v22+.
• PostgreSQL: v14+ (Local, Supabase, or Neon)

1. Installation

git clone https://github.com/matheshwaran-io/Electify.git
cd Electify
npm ci

2. Configure Environment Variables

Copy .env.example to both .env.local (read by Next.js and npm test) and .env (read by drizzle-kit, db:seed and db:reset):

cp .env.example .env.local && cp .env.example .env

Windows PowerShell: Copy-Item .env.example .env.local; Copy-Item .env.example .env Fill in your database URL and a 32+ character JWT secret:

DATABASE_URL="postgresql://postgres:password@localhost:5432/electify"
DIRECT_URL="postgresql://postgres:password@localhost:5432/electify"
JWT_SECRET="your-secure-random-secret-at-least-32-chars-long"

3. Apply Migrations & Seed Database

⚠️ db:push, db:seed and db:reset act on the database in .env without asking which host it is. Use them on a local, new database only. npm run db:migrate is not a supported path (its journal covers only migrations 0000–0002). See the maintenance manual §7.4 and §14.

# Create the tables from the schema (new, empty database only)
npm run db:push

# Seed university hierarchy and Root Administrator
npm run db:seed

4. Running Checks & Tests

# Run unit tests (fast, no database required)
npm run test:unit

# Run full integration test suite (requires PostgreSQL; WRITES fixture rows).
# `npm test` loads .env.local — point it at a LOCAL test database explicitly:
DATABASE_URL=postgresql://localhost:5432/electify_test DIRECT_URL=postgresql://localhost:5432/electify_test npm test

# End-to-end tests (local PostgreSQL + Chrome; recreates the throwaway electify_e2e DB)
npm run test:e2e

# Type-check TypeScript codebase
npm run typecheck

# Run ESLint on source code
npm run lint

# Run ESLint on scripts and tests
npx eslint scripts tests --format compact

5. Start Development Server

npm run dev

Open http://localhost:3000 to view the application.

6. Production Build

npm run build
npm start

---

❓ Troubleshooting & FAQs

1. Database Connection Timeout (ENOTFOUND or connection refused)

• Symptom: Failed query: SELECT 1 or getaddrinfo ENOTFOUND.
• Solution: Ensure your PostgreSQL instance is running and reachable. For cloud databases (Supabase/Neon), verify that your project is not paused and that network access is allowed.

2. JWT Secret Length Warning

• Symptom: FATAL: JWT_SECRET must be configured with a secure random key in production.
• Solution: Set JWT_SECRET in .env.local to a random string of at least 32 characters: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))".

3. Root Admin Bootstrapping in Production

• Symptom: Root admin account does not exist after deploying to a new database.
• Solution: Set SETUP_SECRET in your environment variables, then invoke /api/health?setup=true passing x-setup-secret: <YOUR_SETUP_SECRET> in the header.

---

📚 Documentation

Start here (current, source-verified):

• Project Maintenance Manual — architecture, data model, workflows, safe maintenance, security, known issues
• Architecture · Development Setup · Deployment · Testing
• Repository Cleanup Report
• Windows Setup Guide · Contributing · Security Policy

Older design notes (some sections superseded — see the banner in each file):

• Architecture Overview
• Folder Structure
• Code Standards
• Testing Guide
• Architecture Decision Records (ADRs)

---

📄 License & Ownership

Copyright © 2026 SRM Institute of Science and Technology. All rights reserved.
Developed for academic elective registration and cohort administration.