A comprehensive one-stop platform for all your JEE preparation needs, featuring AI-powered tutoring, study materials, official papers, previous year questions, and more.
- Features
- Technologies Used
- Getting Started
- Building for Production
- Project Structure
- All versions
- Contributing
- License
- Support
- Computer-Based Test (CBT) Mock Test Engine (
/mock-test): Authentic NTA (JEE Main) and TCS iON (JEE Advanced) full-length 3-hour examination simulator with 3-tier state hierarchy (Zustand -> IndexedDB -> Upstash Redis), multi-device anti-collision lease, official palette states, multi-correct checkbox input with partial marking (MULTI_CORRECT_PARTIAL), Section B 5-of-10 attempt enforcement, automatic Mistake Vault sync with active recall, interactive Time Traps & Speed Wins pacing analytics, and factual Attempt Rate scorecard evaluation. - Previous Year Questions (PYQs): Interactive practice hub with multi-parameter filtering, instant answer evaluation, dedicated question pages (
/question/:slug) with step-by-step KaTeX derivations, and full shift paper explorers (/paper/:slug) with section navigation. - Question Lists & Revision Vaults (
/lists): Create, organize, and practice personalized question lists. Save challenging problems to Favourites, track incorrect answers with an automatic Mistake Vault, share public lists with peers, and bookmark questions with real-time synchronization across PYQ cards, full shift papers, standalone questions, and CBT solution reviews. - AI Tutor: Personalized JEE preparation assistance powered by NextAuth authentication and MongoDB-backed chat history.
- Syllabus Tracker: Track your JEE preparation progress across all subjects with chapter-wise completion tracking and cloud sync.
- Study Materials: Comprehensive resources including interactive Formula Sheets, Universal Unit Converters, a Periodic Table Explorer, and reference books for Physics, Chemistry, and Mathematics.
- Official Papers: Direct access to JEE Main and Advanced official papers and answer keys.
- Blog & Articles: Expert JEE preparation tips, strategies, and study guides with search and category filtering.
- Real-time News: Latest JEE-related news and updates powered by GNews API.
- Contact Form: Email integration for user queries and feedback.
- Modern and responsive UI built with Next.js and Tailwind CSS
- Dark/Light theme support with system preference detection
- Mobile-first design approach
- Smooth animations and crisp, instant interaction states
- SEO optimized with automatic sitemap generation and OpenGraph cards
- Interactive Formula Sheets: Dynamic, chapter-wise formulas rendered with KaTeX for quick revision.
- Universal Unit Converters: High-precision, interactive tools to instantly convert complex derived units across Physics, Chemistry, and Mathematics.
- Periodic Table Explorer: Interactive periodic table featuring s/p/d/f block highlights (fully aligned with NCERT/JEE syllabus standards), properties trends heatmaps (electronegativity, ionization energy, atomic mass, melting point), STP state of matter filters, responsive mobile list views, and high-yield inorganic chemistry study notes.
- Physics Resources: Complete study materials and reference books.
- Chemistry Resources: Comprehensive chemistry study guides.
- Mathematics Resources: Extensive math preparation materials.
- Chapter-Wise Practice Hub (
/previous-year-questions):- Filter by Subject (Physics, Chemistry, Mathematics), Dynamic Chapter cascading, Exam Type (JEE Main / Advanced), Exam Year, Difficulty, and Question Format.
- Custom, instant
CustomSelectdropdown with embedded search filter and zero animation delay. - Interactive self-testing: select options (MCQ / Multi-Correct / Numeric) and click "Check Answer" for instant scoring (
+4 Marks/-1 Mark) and answer verification. - Click-to-zoom high-resolution diagram modal for detailed graphs and circuits.
- "Full Papers" directory tab displaying published shift papers.
- Dedicated Single Question Pages (
/question/[slug]):- Standalone, indexable landing page for every question with dynamic SEO metadata, OpenGraph cards, and JSON-LD breadcrumbs (
Home > PYQs > {question.title}). - Verified answer key and full Step-by-Step KaTeX Derivation with mathematical steps and diagrams.
- One-click question URL sharing with clipboard feedback.
- Standalone, indexable landing page for every question with dynamic SEO metadata, OpenGraph cards, and JSON-LD breadcrumbs (
- Dedicated Full Paper Pages (
/paper/[slug]):- Complete official shift paper viewer with responsive 2-Tier Subject & Section Navigator (
Physics Sec A/B,Chemistry Sec A/B,Mathematics Sec A/B). - Real-time URL query parameter synchronization (
?subject=...§ion=...) to persist active state across reloads. - Sequential paper question numbering (
Q1..Q90) and external solution links opening in new tabs.
- Complete official shift paper viewer with responsive 2-Tier Subject & Section Navigator (
📖 Full Architectural Specification: See the comprehensive CBT Engine Master Blueprint & Technical Specification for deep technical details on the 3-tier state hierarchy, single-instance leased mutex, scoring judge algorithms, and authoritative MongoDB schemas.
- Authentic Examination Interfaces (
/mock-test):- JEE Main Terminal: Official NTA CBT software replica with 6-section navigation (
Physics/Chem/Math Sec A & B), synchronized master countdown timer, Question Paper preview, Instructions modal, and official 5-state Question Palette (Not Visited, Not Answered, Answered, Marked for Review, Answered & Marked for Review). - JEE Advanced Terminal: TCS iON CBT replica with 2-tier hierarchy (Parts & Sub-Sections), accessibility zoom (
A+ / A / A-), and section-filtered question palette. - Unsaved Palette Jump Trait: Replicates official NTA/IIT examination rules where jumping directly via the palette discards uncommitted choices.
- Virtual Numeric Keypad: Mouse-only on-screen keypad strictly blocking physical keyboard strokes for numerical integer/decimal inputs.
- Multi-Correct Checkbox Support: Dedicated square checkbox controls with simultaneous option toggling and official partial marking (
+4, +3, +2, +1, -2).
- JEE Main Terminal: Official NTA CBT software replica with 6-section navigation (
- Resilient 3-Tier State Architecture:
- Layer 1: Visual State (Zustand, 0 ms UI updates).
- Layer 2: Local Crash Guard (IndexedDB
<1 mspersistence against accidental browser close). - Layer 3: Cloud Persistence (Upstash Redis delta sync via lightweight HTTP REST calls).
- Multi-device leased mutex anti-collision preventing concurrent device cheating (409 Conflict lockout overlay).
- Zero-Knowledge Security & Authentic Question Resumption: Dedicated
/cbt/papers/:slugmicroservice endpoint delivering questions stripped of solutions, answers, and hints. Resumes seamlessly on the exact active question on page reload or device transfer matching TCS iON center behavior.
- Comprehensive Scorecard & Pacing Analytics (
/mock-test/[slug]/results):- Factual Attempt Rate: Replaced pseudo-percentiles with accurate attempted question ratios (
Attempt Rate: 84.0% (63/75)). - Interactive Time Traps & Speed Wins: Benchmark pacing dashboard with click-to-jump smooth scrolling and amber focus highlight pulse.
- Mistake Vault with Active Recall: Automatically stores incorrect attempts in MongoDB Atlas with step-by-step solutions collapsed and closed by default.
- In-Situ Bug Reporting: Direct
<Bug />report trigger on every review card linking intoReportQuestionModal.
- Factual Attempt Rate: Replaced pseudo-percentiles with accurate attempted question ratios (
📖 Full Architectural Specification: See the comprehensive Question Playlists & Custom Bookmarks Master Blueprint for data schemas, Go microservice endpoints, and state synchronization details.
- Personalized Revision Playlists (
/lists):- System-seeded default lists: Favourites (priority revision) and Mistake Vault (revision tracker).
- Create custom lists with personalized titles, descriptions, and public/private visibility toggles.
- Search, sort, and filter bookmarked questions by Subject, Difficulty, and Chapter with progressive infinite scroll.
- Direct "Solve" shortcuts navigating to standalone question solver pages.
- Public playlist sharing with one-click link copying and clone-to-account capability for peers and study groups.
- Universal Question Bookmarking:
- Embedded
<QuestionBookmarkButton />consistently available across all four question surfaces:- PYQ Question Cards (
/previous-year-questions) - Full Shift Paper Explorers (
/paper/[slug]) - Dedicated Question Pages (
/question/[slug]) - CBT Exam Solution Reviews (
/mock-test/[slug]/results)
- PYQ Question Cards (
- One-click multi-playlist checkbox selector with instant in-flight mutation and in-popover custom list creation.
- Direct "Sign In to Bookmark" call-to-action for guest visitors with automatic post-login return.
- Embedded
- Real-Time State Synchronization:
- Single source of truth via unified global
BookmarkContextat the application root (ConditionalLayout). - Zero duplicate network requests; adding, editing, or deleting lists immediately updates bookmark popovers across the entire platform without page refreshes.
- Single source of truth via unified global
- Authentication via NextAuth.js (Google OAuth)
- File upload and attachment support
- Markdown and LaTeX rendering for mathematical expressions
- Chat history persistence backed by MongoDB
- Real-time message streaming
- Progress tracking for Physics, Chemistry, and Mathematics
- Chapter-wise completion tracking for Theory, PYQs, and Revision
- Visual progress indicators and statistics
- Cloud Sync: Securely backup and sync your progress across multiple devices (MongoDB backed)
- Smart Merge Conflict Resolution: Intuitive UI to merge or choose between browser and cloud data
- Export progress as an image with
html-to-image - Import/export progress data manually via JSON
- Local storage persistence with automatic cross-tab synchronization
- Motivation-driven progress visualization
- Subject-wise progress overview
- Real-time JEE news from GNews API
- Categorized news cards
- Automatic content refresh
- Mobile-responsive news layout
- Expert preparation tips and strategies
- Subject-wise study guides and book recommendations
- Time management and common mistakes advice
- MDX-based article system with frontmatter metadata
- Search and category filtering
- Featured article highlighting
- Reading progress tracking with table of contents
- Social sharing integration
- SEO optimized with structured data
- Framework: Next.js 16 with App Router
- UI Library: React 19
- Styling: Tailwind CSS with custom animations and
tailwind-scrollbarfor tailored component scrollbars - Icons: Lucide React & React Icons
- Theme Management: @teispace/next-themes
- Floating UI: @floating-ui/react for tooltips and popovers
- Markdown & Math Rendering: Custom
MarkdownMathRendererbuilt with KaTeX,remark-math,rehype-katex, andremark-gfm - Heading Anchors: rehype-slug for blog table of contents
- Content Management: gray-matter for MDX frontmatter parsing
- Image Export: html-to-image for exporting the Syllabus Tracker
- Auto-resize Textarea: react-textarea-autosize for the AI Tutor chat input
- Unified Service Layer (
server/services/): Centralized internal SDK and single source of truth for microservice communication, token signing, and caching rules:pyqs.js: Go PYQ & CBT microservice client (pyqs-api.jeechallenger.com) for questions, papers, attempts, mistake vault, and test submissions.ai.js: Python AI Tutor microservice client (ai-api.jeechallenger.com) with streaming chat proxy and multipart file upload forwarding.syllabus-tracker.js: Syllabus tracker microservice client delegating progress synchronization and milestone retrieval to the Go PYQs microservice (pyqs-api.jeechallenger.com).
- Authentication: NextAuth.js v4 with Google OAuth provider & HS256 JWT microservice authentication tokens
- Databases (Microservice Architecture):
jee_challenger_auth: User sessions, accounts, and authentication (direct NextAuth adapter connection; indexed onemail,created_at,subscription_plan_id, andaccounts.userId)jee_challenger_ai: AI Tutor chat history and message logs (owned by FastAPI AI backend)jee_challenger_pyqs&jee_challenger_syllabus_tracker: Question bank, paper metadata, CBT test scorecards, mistake vault, revision playlists, and syllabus progress (owned and served exclusively by the high-performance Go microservice)
- Caching & Live CBT State: Upstash Redis (session locks, heartbeat sync, and kiosk device transfer)
- Token Handling: Centralized
jsonwebtoken(JWT) signing withNEXTAUTH_SECRET - Email Service: Nodemailer for contact form
- News API: GNews API for real-time updates
- BFF API Routes (
app/api/): Next.js Backend-For-Frontend API routes serving as secure browser-to-backend proxies and external webhook receivers
- Build Tool: Turbopack for faster development
- SEO: next-sitemap for automatic sitemap generation
- Analytics: @next/third-parties for Google Analytics integration
- Ad Integration: Google AdSense support
- Performance: Image optimization, caching headers, and production webpack chunk splitting
- Deployment: Vercel
- Clone the repository:
git clone https://github.com/Samya-S/jeechallenger-app.git
cd jeechallenger-app- Install dependencies:
npm install- Create a
.env.localfile in the root directory and add your environment variables:
# NextAuth Configuration
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-nextauth-secret
# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
# MongoDB Connection
MONGODB_URI=your-mongodb-connection-string
# Upstash Redis (Session Management & CBT State)
UPSTASH_REDIS_REST_URL=your-upstash-redis-url
UPSTASH_REDIS_REST_TOKEN=your-upstash-redis-token
# Email Configuration (Nodemailer / Generic SMTP)
SMTP_HOST=your-smtp-host
SMTP_PORT=465 # 465 (SSL) or 587 (STARTTLS)
SMTP_SECURE=true # true for 465, false for 587/2525
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SENDER_EMAIL="Support <noreply@example.com>"
RECEIVER_EMAILS=admin@example.com
# GNews API Configuration
GNEWS_API_KEY=your-gnews-api-key
# Site Configuration
NEXT_PUBLIC_SITE_URL=http://localhost:3000
# Cloudflare Analytics (Optional)
NEXT_PUBLIC_CLOUDFLARE_ANALYTICS_TOKEN=your-token
# Google Analytics (Optional)
NEXT_PUBLIC_GA_MEASUREMENT_ID=your-ga-id
# Google AdSense (Optional)
NEXT_PUBLIC_ADSENSE_CLIENT_ID=your-adsense-id
# Internal Cron Secret (Required for Cloudflare Worker CBT auto-submit)
INTERNAL_CRON_SECRET=your-cron-secret
# On-Demand Revalidation Secret (for Go backend & pipeline cache purges)
REVALIDATION_SECRET=your-revalidation-secret
# Microservice Internal Machine-to-Machine Secrets (HS256 X-Internal-Token)
PYQS_SERVICE_SECRET=your-pyqs-service-secret
AI_SERVICE_SECRET=your-ai-service-secret
# PYQ Go Backend Microservice URL (optional, defaults to https://pyqs-api.jeechallenger.com)
PYQS_API_URL=https://pyqs-api.jeechallenger.com
# AI Tutor Python Backend Microservice URL (optional, defaults to https://ai-api.jeechallenger.com)
AI_API_URL=https://ai-api.jeechallenger.com- Run the development server:
npm run dev- Open http://localhost:3000 with your browser to see the result.
To create an optimized production build:
npm run buildThis will run Turbopack production compilation, Next.js page generation, sitemap generation, and static SEO XML outputs.
jeechallenger-app/
├── app/ # Next.js App Router routes
│ ├── (about)/ # About pages (contact-us, donate, etc.)
│ ├── (home)/ # Homepage components, layout, and modular showcase
│ │ └── components/feature-hub/ # Decoupled demo widgets (CBT, PYQ, AI Tutor, Syllabus, Resources, Official, Blogs) and mock data
│ ├── (legal)/ # Legal pages (privacy-policy, terms-of-service, etc.)
│ ├── (official-links)/ # JEE Main and Advanced official resource portals
│ ├── (pyqs)/ # Previous Year Questions hub, /paper/[slug], /question/[slug]
│ ├── (read-more)/ # Blogs and news pages
│ ├── (resources)/ # Formula sheets, Unit converters, Periodic Table explorer
│ ├── (seo)/ # Sitemap, RSS, and OpenGraph generators
│ ├── (user)/ # Login and candidate user profile dashboard
│ ├── ai-tutor/ # AI Tutor chat interface and attachment uploaders
│ │ ├── components/ # ChatMessageList, ChatInputArea, WelcomeScreen, ChatSidebar, AITutorNavbar
│ │ └── utils/ # aiTutorUtils.js (date grouping, error normalization, dynamic placeholders)
│ ├── api/ # Backend-For-Frontend (BFF) API routes
│ │ ├── ai/ # Proxy to FastAPI AI Tutor microservice via aiService
│ │ ├── auth/ # NextAuth API endpoints & Google OAuth callbacks
│ │ ├── cbt/ # CBT Redis session management, heartbeat sync, and submit
│ │ ├── playlists/ # User playlists & bookmarks CRUD routes
│ │ ├── pyqs/ # Proxy to Go PYQ microservice & cache purge webhook (revalidate)
│ │ └── syllabus-tracker/ # Syllabus tracker sync API
│ ├── lists/ # Custom question playlists and bookmarks (/lists/[slug])
│ ├── mock-test/ # Official timed CBT Mock Test simulator & Mistake Vault
│ └── syllabus-tracker/ # Cloud-synced preparation tracking system
│ └── components/ # SyllabusToolbar, SyllabusOverviewCard, SyllabusFilterBar, and progress cards
├── components/ # Reusable React components
│ ├── cbt/ # CBT exam rooms, palettes, scorecards, and solution review
│ │ └── hub/ # CBTHubComponent, CBTHubPerformanceStrip, and tabs/ (papers, attempts, vault)
│ ├── common/ # Shared components (Breadcrumbs, MarkdownMathRenderer, etc.)
│ ├── modals/ # Modal dialogs
│ ├── playlists/ # Unified BookmarkContext, sidebars, tables, and popover components
│ ├── providers/ # React Context providers
│ ├── resources/ # Formula sheets, unit converters, and PYQ components
│ │ └── pyqs/ # PaperDetailComponent, PYQImageLightbox, and modular paper views
│ │ └── paper-detail/ # PaperHeader, PaperNavigation, and PaperQuestionCard subcomponents
│ └── ui/ # Primitives (CustomSelect, BlogCard, etc.)
├── config/ # Configuration files
├── data/ # Static resource data and formula constants
├── docs/ # Technical blueprints and specifications
│ ├── assets/ # Technical documentation diagrams and assets
│ ├── blog-structure.md # Blog system documentation
│ ├── cbt-master-spec.md # CBT Exam Simulator & 3-Tier State Machine master blueprint
│ ├── color-system.md # Design system colors
│ ├── playlists-master-spec.md# Question Playlists & Custom Bookmarks master blueprint
│ ├── product-vision.md # Platform vision and goals
│ └── traffic-growth-strategy.md # Traffic, SEO, and indexing strategy
├── public/ # Static assets
├── scripts/ # Build, testing, and SEO automation scripts
│ ├── generate-static-seo.mjs # Static SEO XML and sitemap generator
│ └── test-contact-actions.mjs# Contact form action test runner
├── server/ # Server-side business logic
│ ├── services/ # Centralized microservice clients & SDKs
│ │ ├── ai.js # Python AI Tutor microservice client
│ │ ├── internal-token.js # Short-lived internal service JWT signer (X-Internal-Token)
│ │ ├── pyqs.js # Go PYQ & CBT microservice client
│ │ └── syllabus-tracker.js # Syllabus progress Go microservice client
│ ├── contact-actions.js # Contact form email server action
│ ├── news-actions.js # GNews server action
│ └── views-actions.js # Upstash Redis article view counts
└── utils/ # Low-level utilities & infrastructure singletons
├── articles.js # Blog and article loading utilities
├── cbt-auto-submit.js # Lazy & cron expired CBT exam finalizer
├── cbt-helpers.js # CBT palette, timer, and score formatting helpers
├── modal-events.js # Global custom event bus for modals
├── mongodb.js # MongoDB client singleton
├── og-image.jsx # Edge JSX OpenGraph image generator template
├── og-metadata.js # Route-level OpenGraph & Twitter metadata generator
├── pyq-helpers.js # PYQ taxonomy, slugs, badges, and search snippet helpers
└── redis.js # Upstash Redis client singleton
Upgraded the vanilla JavaScript project to a modern Next.js application with many more features.
Note
This is a major update and is managed in this repository.
This is version 1.2, made using HTML, CSS and vanilla JavaScript. The code is available at Samya-S/jeechallenger-v1.2 (archived).
This version includes PHP. The code is available at Samya-S/jeechallenger-v1.1 (archived).
This version is made using HTML, CSS and vanilla JavaScript. The code is available at Samya-S/jeechallenger-v1.0 (archived).
Contributions are welcome! Please feel free to submit a Pull Request.
- Follow the existing code structure and naming conventions
- Ensure responsive design for all new components
- Add proper TypeScript types if applicable
- Test on both light and dark themes
- Update documentation for new features
This project is licensed under the MIT License - see the LICENSE file for details.
Join our community:
- 💬 Telegram: t.me/jeechallenger
- 📸 Instagram: @jeechallenger
- 🎥 YouTube: @jeechallenger
If you find this project helpful and would like to support its development, consider becoming a sponsor. Your support helps maintain and improve the project.