QuestionWhiz - AI Quiz and Question Generator

QuestionWhiz is a full-stack web application that turns text, topics, documents, images, audio and video into ready-to-use quizzes and study questions with AI. It combines a React 18 + Vite frontend with a FastAPI (Python) backend and uses Supabase for authentication and storage. It suits educators, schools, tutoring businesses, ed-tech founders and developers who want a working assessment platform to run or customize.

Flexible source inputs

• Paste text such as articles, excerpts or lecture notes 
• Topic-based generation with subtopic, core concepts, constraints and keywords 
• Similar-question generation from an existing question 
• Multi-file upload for PDF and DOCX documents, images, audio and video

Pedagogical control

• All six Bloom's Taxonomy levels: Remember, Understand, Apply, Analyze, Evaluate, Create 
• Easy, Medium and Hard difficulty 
• Multiple Choice (A/B/C/D, 1/2/3/4 or a/b/c/d), True/False and Fill in the Blanks 
• Optional answer keys and step-by-step explanations

Multi-provider AI (Bring Your Own Key)

• Supports Google Gemini, OpenAI, Groq and Mistral AI 
• Users add their own API keys in the app; keys are kept in browser local storage and sent per request 
• Vision models read images; Gemini processes audio and video

Dashboard, history and export

• Dashboard with generation analytics, question metrics and recent activity 
• Quiz history with copy and re-export 
• Client-side export to DOCX and PDF 
• Installable as a Progressive Web App (PWA)

Security

• Supabase email/password and Google OAuth sign-in 
• Server-side JWT verification (HS256 and RS256/ES256 via JWKS) 
• Per-IP rate limiting and Pydantic input validation

Technology stack

React 18, Vite, React Router v6, Tailwind CSS, Python, FastAPI, Uvicorn, Pydantic, SlowAPI, Supabase (Auth + PostgreSQL), PyPDF2, docx, jspdf, file-saver.

What's included

• Complete source code (frontend and backend) 
• README, installation guide, configuration guide and user guide 
• Illustrated, printable PDF user manual

Requirements

• Python 3.10+ and Node.js 18+ 
• A Supabase project (the free tier is enough to start) 
• At least one AI provider API key (Gemini, OpenAI, Groq or Mistral) 
• Hosting for the backend and a static host for the frontend if deploying publicly

Please note

• AI provider usage is billed by the provider and is not included in the purchase. 
• Image, audio and video features depend on the provider (Gemini or OpenAI for images, Gemini for audio and video). 
• Review generated questions for accuracy before using them in graded assessments. 
• Setup requires basic familiarity with Python, Node.js and environment configuration.

Features

• Generate questions from text, topics, PDF, DOCX, images, audio and video 
• Multiple Choice, True/False and Fill in the Blanks 
• Bloom's Taxonomy levels and Easy/Medium/Hard difficulty 
• Answer keys and step-by-step explanations 
• Supports Gemini, OpenAI, Groq and Mistral (Bring Your Own Key) 
• Export to DOCX and PDF 
• Quiz history, copy and re-export 
• Dashboard with generation analytics 
• Supabase email and Google OAuth sign-in 
• Installable PWA 
• Detailed documentation and illustrated PDF manual

Requirements

• Python 3.10 or newer, with pip 
• Node.js 18 or newer, with npm 
• A Supabase project (Project URL, API key and JWT secret; Email and Google OAuth providers if needed) 
• At least one AI provider API key: Google Gemini, OpenAI, Groq or Mistral AI 
• Gemini or OpenAI key for image input, and a Gemini key for audio and video input 
• A modern web browser (Chrome, Edge, Firefox or Safari) 
• For public deployment: a server or host for the FastAPI backend, a static host for the frontend, and HTTPS

Instructions

1. Extract the package and open a terminal in the project folder. It contains backend/ and frontend/. 
2. Create a Supabase project at supabase.com. Note the Project URL, the API keys and the JWT secret. Enable the Email provider, and Google OAuth if you want it. Set the Site URL and Redirect URLs to your frontend address. 
3. Set up the backend:    

   cd backend
   python -m venv venv
   # Windows: .venvScriptsActivate.ps1
   # macOS/Linux: source venv/bin/activate
   pip install -r requirements.txt
   

      
4. Configure the backend. Create backend/.env with SUPABASE_URL, SUPABASE_KEY and SUPABASE_JWT_SECRET. 

Start the backend: python main.py. It runs at http://127.0.0.1:8081.  Set up the frontend in a second terminal:    

cd frontend
npm install

    Configure the frontend. Create frontend/.env with your Supabase URL, anon key and backend URL.  Start the frontend: npm run dev, then open the address shown (typically http://localhost:5173).  Sign up or sign in, open the API keys area and add your Gemini, OpenAI, Groq or Mistral key.  Generate questions: choose a source (text, topic, similar question or files), set the question type, Bloom's level and difficulty, then click Generate.  Export to DOCX or PDF, or review earlier quizzes in History.  For production, run npm run build for the frontend and serve the output from a static host. Run the backend behind a process manager and HTTPS.

Full details are in the included README, INSTALLATION, CONFIGURATION and USER_GUIDE files and the PDF manual.