NoteQuest

Turn study notes into quests, quizzes, streaks, and measurable progress.

AI-powered study tracker • Quiz generation • XP & streaks • Analytics • Leaderboards

---

Overview

NoteQuest is an AI-powered learning platform that transforms raw study notes into structured subjects, chapters, and topics.

Using AI-powered topic extraction, NoteQuest helps learners organize material, track progress, complete quizzes, maintain study streaks, earn XP, and build consistent learning habits through gamification.

Whether you're preparing for exams, learning a new subject, or managing large volumes of notes, NoteQuest converts unstructured information into an actionable study roadmap.

AI Provider Agnostic

NoteQuest is designed to be AI-provider agnostic.

While this demo currently uses the Groq API for topic extraction, quiz generation, study tips, and daily challenges, the application architecture is not tied to any specific AI provider.

Any LLM API capable of processing prompts and returning structured responses can be integrated with minimal changes, including:

• Groq
• OpenAI
• Google Gemini
• Anthropic Claude
• OpenRouter
• Self-hosted models via Ollama
• Other OpenAI-compatible APIs

Groq is used in this repository because it provides a cost-effective way to power AI features during development and demonstration. The underlying architecture allows providers to be swapped without significant changes to the application.

---

Current Status

🚧 Demo Release

NoteQuest is currently an active demonstration project showcasing AI-assisted study planning, quiz generation, progress tracking, and gamified learning.

Current development focuses on:

• Improving AI extraction accuracy
• Expanding quiz generation capabilities
• Enhancing analytics and insights
• Improving mobile responsiveness
• Refining the overall user experience

Screenshots

Features

• AI topic extraction from pasted notes or uploaded files.
• Upload support for .txt and text-based .pdf files (up to first 30 pages extracted).
• Subject dashboard with topic completion, progress tracking, and learning roadmaps.
• Gamification: XP, levels, streaks, completion rewards, and badges.
• Daily AI challenge and smart revision suggestions.
• Chapter-based quiz generation with XP rewards.
• Study analytics (heatmap, velocity trends, completion estimates).
• Optional Supabase-powered global leaderboard.
• Light/dark theme support with persisted preference.

Tech Stack

Layer	Technology
Frontend	React 19
Routing	React Router 7
Build Tool	Vite 8
Styling	Tailwind CSS
AI Integration	Groq API (demo implementation)
Database	Supabase
PDF Processing	pdfjs-dist
Local Persistence	Browser localStorage
Deployment	Vercel

Architecture

User Notes / PDF
        │
        ▼
AI Processing Layer
        │
        ▼
Topic Extraction
        │
        ▼
Structured JSON
        │
        ▼
Subject / Chapter / Topic Store
        │
        ├── Progress Tracking
        ├── Quiz Generation
        ├── Revision Planning
        ├── XP & Streak System
        ├── Analytics Engine
        └── Leaderboard Integration

Project Structure

src/
	components/
		UploadNotes.jsx
		TopicBoard.jsx
		ProgressBar.jsx
		Roadmap.jsx
		SmartRevision.jsx
		DailyChallenge.jsx
		StudyHeatmap.jsx
		VelocityChart.jsx
		Leaderboard.jsx
		...
	hooks/
		useToast.js
	pages/
		Home.jsx
		Upload.jsx
		Dashboard.jsx
		SubjectDetail.jsx
		Quiz.jsx
		LeaderboardPage.jsx
		Notes.jsx
		Settings.jsx
		profile.jsx
	utils/
		gemini.js
		storage.js
		supabase.js
		theme.js
	App.jsx
	main.jsx

Getting Started

1. Prerequisites

• Node.js 18+
• npm 9+

2. Install dependencies

npm install

3. Configure environment variables

Copy .env.example to .env and fill in the values:

VITE_GROQ_API_KEY=your_groq_api_key_here
VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

Notes:

• VITE_GROQ_API_KEY is required for AI features (topic extraction, quiz generation, study tips, daily challenge).
• Supabase variables are only required if you want leaderboard sync.

4. Run the app

npm run dev

Open the local URL shown by Vite (usually http://localhost:5173).

Available Scripts

• npm run dev - Start development server
• npm run build - Build production bundle
• npm run preview - Preview production build locally
• npm run lint - Run ESLint

Leaderboard Setup (Supabase)

If you want the online leaderboard, create a leaderboard table in Supabase.

Example SQL:

create table if not exists leaderboard (
	id bigint generated always as identity primary key,
	username text not null unique,
	xp integer not null default 0,
	level text not null default 'Novice',
	subjects_count integer not null default 0,
	topics_completed integer not null default 0,
	streak integer not null default 0,
	updated_at timestamptz not null default now()
);

Then enable read/write policies suitable for your project environment.

How Data Is Stored

• Core progress and app state are stored in browser localStorage.
• Leaderboard data is stored in Supabase when configured.
• Theme preference is persisted and synced across open tabs.

AI Workflow

1. User uploads notes (text or PDF) in Upload.
2. Notes are sent to Groq (llama-3.3-70b-versatile) to produce structured JSON.
3. Parsed subjects/chapters/topics are saved locally.
4. Dashboard and subject pages drive progress, XP, revision plans, and analytics.

Build and Deployment

Production build

npm run build

The production output is generated in dist/.

Vercel

This repository includes vercel.json and is ready for Vercel deployment.

Troubleshooting

• AI extraction fails:
  • Confirm VITE_GROQ_API_KEY is set correctly.
  • Check API quota/rate limits.
• PDF upload returns no text:
  • Use text-based PDFs (not scanned images).
  • Very large PDFs are truncated to first 30 pages.
• Leaderboard errors:
  • Verify Supabase URL/key and table schema.
  • Ensure your table permissions/policies allow expected operations.

---

License

This project is licensed under the MIT License.
Permission is hereby granted, free of charge, to any person 
obtaining a copy of this software and associated documentation  
files (the "Software"), to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, 
subject to the conditions of the MIT License.

See the LICENSE file for the full license text.