quizEZ

An AI-powered web application for generating educational quizzes from text content, enabling students and learners to quickly create practice tests and improve their active recall learning.

Project Description

quizEZ addresses the challenge of time-consuming manual quiz creation by leveraging artificial intelligence to automatically generate multiple-choice (ABCD) and true/false questions from pasted text. The application streamlines the learning process by allowing users to:

• Generate quiz questions instantly from educational content
• Review and edit AI-generated questions before saving
• Take quizzes with immediate feedback
• Track their learning progress and quiz history

The MVP focuses on core functionality to validate the product value for students and learners, prioritizing stability and ease of editing over feature quantity.

Tech Stack

Frontend

• Astro 5 - Modern web framework for building fast, content-focused websites with minimal JavaScript
• React 19 - UI library for building interactive components
• TypeScript 5 - Type-safe JavaScript for better code quality and IDE support
• Tailwind CSS 4 - Utility-first CSS framework for rapid UI development
• Shadcn/ui - High-quality React component library built on Radix UI

Backend

• Supabase - Backend-as-a-Service providing:
  • PostgreSQL database
  • Built-in user authentication
  • Multi-language SDK support
  • Open-source solution with self-hosting options

AI Integration

• OpenRouter.ai - AI model gateway providing:
  • Access to multiple AI models (OpenAI, Anthropic, Google, and more)
  • Cost-effective model selection
  • Financial API key limits

Testing

• Vitest - Fast unit testing framework optimized for Vite-based projects
  • Native TypeScript support
  • Compatible with Jest API
  • Built-in code coverage
• Playwright - Modern E2E testing framework
  • Multi-browser testing (Chromium, Firefox, WebKit)
  • Auto-wait capabilities
  • Built-in test runner and assertions

DevOps & Hosting

• GitHub Actions - CI/CD pipeline automation
• DigitalOcean - Application hosting via Docker containers

Getting Started Locally

Prerequisites

• Node.js v22.14.0 (as specified in .nvmrc)
  • If using nvm, run: nvm use or nvm install 22.14.0
• npm (comes with Node.js)
• Supabase CLI and Docker (for local development) – the project requires a running Supabase instance (local or linked remote) to work

Installation

1. Clone the repository:

git clone <repository-url>
cd quizEZ

2. Install dependencies:

npm install

3. Set up environment variables:

   • Create a .env file in the root directory
   • Configure Supabase credentials (database URL, anon key, service role key)
   • Configure OpenRouter.ai API key
   • Add any other required environment variables

4. Start Supabase (required for the project to work):

   • Local: Run npx supabase start (requires Docker). On first run, this may take a few minutes while images download. Supabase Studio is at http://127.0.0.1:54323; the API is at http://127.0.0.1:54321.
   • Remote: Link your project with npx supabase link, then use your hosted project’s credentials in .env.

5. Run the development server:

npm run dev

The application will be available at http://localhost:4321 (or the port specified by Astro).

6. Build for production:

npm run build

7. Preview production build:

npm run preview

Available Scripts

Development

• npm run dev - Start the Astro development server with hot module replacement
• npm run build - Build the application for production
• npm run preview - Preview the production build locally
• npm run astro - Run Astro CLI commands

Code Quality

• npm run lint - Run ESLint to check for code quality issues
• npm run lint:fix - Automatically fix ESLint issues where possible
• npm run format - Format code using Prettier

Testing

Unit Tests (Vitest)

• npm test - Run unit tests
• npm run test:watch - Run unit tests in watch mode
• npm run test:ui - Run unit tests with interactive UI
• npm run test:coverage - Generate test coverage report

E2E Tests (Playwright)

• npm run test:e2e - Run E2E tests
• npm run test:e2e:ui - Run E2E tests with interactive UI
• npm run test:e2e:debug - Run E2E tests in debug mode
• npm run test:e2e:report - Show the last test report

For more details on testing, see TESTING.md.

Project Scope

MVP Features (In Scope)

• User Authentication: Email/password registration and login
• AI Question Generation: Generate quiz questions from pasted text (2000 character limit per generation)
• Question Verification: Review, edit, accept, or reject AI-generated questions before saving
• Quiz Management: Simple flat list of saved quizzes with options to start, edit name, or delete
• Quiz Taking: Solve quizzes with immediate feedback (green/red indicators and correct answer display)
• Result History: Track quiz attempts with dates and scores, including detailed view of incorrect answers

Out of Scope (Future Considerations)

• File upload support (PDF, DOCX) - text input only in MVP
• Multiplayer/live game modes
• Advanced question types (open-ended, matching pairs)
• Public quiz sharing
• Mobile app - desktop-optimized web version only
• Payment and subscription systems - no daily generation limits in MVP
• Advanced organization (folders, tags) - flat list only in MVP

Success Criteria

The MVP aims for 75% of AI-generated questions to be accepted by users without any edits, measured through telemetry tracking:

• Question_Accepted - Saved without edits
• Question_Edited - Saved after editing
• Question_Rejected - Removed from quiz

Project Status

🚧 Early Development / MVP Phase

This project is currently in active development, focusing on MVP features as outlined in the Project Scope. The priority is on:

• Stable AI question generation
• Intuitive editing and verification workflow
• Reliable quiz taking experience

Contributions, feedback, and issue reports are welcome as we work towards a stable MVP release.

License

MIT