An intelligent AI-powered quiz application that adapts to your learning style and challenges you to grow. Built with Next.js and powered by Google's Gemini AI.
- Smart Question Creation: Generate contextually relevant questions using Google's Gemini 2.0 Flash API
- Adaptive Difficulty: Choose from multiple difficulty levels that match your skill level
- Custom Topics: Create quizzes on any topic you want to learn about
- Detailed Explanations: Get comprehensive explanations for each answer
- Secure Authentication: Google OAuth integration via NextAuth.js
- Quiz History: Track your progress and revisit previous quizzes
- Performance Analytics: Visualize your results with interactive charts
- Responsive Design: Perfect experience across desktop, tablet, and mobile devices
- Dark/Light Theme: Toggle between themes for comfortable studying
- Result Visualization: Pie charts and analytics to understand your performance
- Topic-Based Progress: Track improvement across different subjects
- Quiz Reattempts: Retake quizzes to improve your scores
- Node.js 18+ and npm/yarn
- MongoDB database (local or cloud)
- Google OAuth credentials
- Google Gemini API key
-
Clone the repository
git clone https://github.com/Frank2006x/Quizium.git cd Quizium -
Install dependencies
npm install # or yarn install -
Environment Setup
Create a
.env.localfile in the root directory:# Database MONGODB_URI=your_mongodb_connection_string # NextAuth Configuration NEXTAUTH_URL=http://localhost:3000 NEXTAUTH_SECRET=your_nextauth_secret_key # Google OAuth GOOGLE_CLIENT_ID=your_google_client_id GOOGLE_CLIENT_SECRET=your_google_client_secret # Google Gemini API GEMINI_API_KEY=your_gemini_api_key
-
Set up Google OAuth
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable Google+ API
- Create OAuth 2.0 credentials
- Add authorized redirect URIs:
http://localhost:3000/api/auth/callback/google
-
Set up Google Gemini API
- Visit Google AI Studio
- Generate an API key for Gemini
- Add the key to your environment variables
-
Run the development server
npm run dev # or yarn dev -
Open your browser
Navigate to http://localhost:3000
src/
├── app/ # Next.js 13+ App Router
│ ├── api/ # API routes
│ │ ├── auth/ # Authentication endpoints
│ │ ├── generate/ # Quiz generation endpoint
│ │ ├── getQuestion/ # Question retrieval
│ │ └── topics/ # Topic management
│ ├── home/ # Home page
│ ├── quiz/ # Quiz pages
│ └── layout.tsx # Root layout
├── components/ # Reusable UI components
│ ├── ui/ # Base UI components (Radix UI)
│ ├── magicui/ # Enhanced UI components
│ └── *.tsx # Feature-specific components
├── hooks/ # Custom React hooks
├── lib/ # Utility libraries
│ └── mongodb.ts # Database connection
├── models/ # Mongoose schemas
│ ├── quiz.modal.ts # Quiz data model
│ └── session.model.ts # User session model
└── store/ # Zustand state management
└── useQues.ts # Quiz state store
- Framework: Next.js 15.3.4 with App Router
- Language: TypeScript
- Styling: Tailwind CSS
- UI Components: Radix UI
- Icons: Lucide React, Tabler Icons
- Charts: Recharts
- State Management: Zustand
- Theme: next-themes
- Runtime: Node.js
- Database: MongoDB with Mongoose
- Authentication: NextAuth.js with Google OAuth
- AI Integration: Google Gemini 2.0 Flash API
- Linting: ESLint with Next.js config
- Package Manager: npm/yarn
- Deployment: Vercel
- Sign in with your Google account
- Choose a topic you want to be quizzed on
- Select difficulty level (Easy, Medium, Hard)
- Click "Generate Quiz" and wait for AI to create questions
- Answer questions and get instant feedback
- View results with detailed explanations
- Quiz History: Access all your previous quizzes from the sidebar
- Reattempt Quizzes: Improve your scores by retaking quizzes
- Track Performance: View analytics and progress charts
- Delete Quizzes: Remove unwanted quiz records
POST /api/generate
Body: { topic: string, difficulty: string }
Response: { success: boolean, data: QuizQuestion[] }
POST /api/getQuestion
Body: { userId: string }
Response: { questions: QuizQuestion[] }
GET /api/topics
Response: { topics: string[] }
DELETE /api/deleteQuiz
Body: { quizId: string }
Response: { success: boolean }
- Connect GitHub repository to Vercel
- Add environment variables in Vercel dashboard
- Deploy automatically on push to main branch
-
Build the application
npm run build
-
Start production server
npm run start
We welcome contributions! Please follow these steps:
- Fork the repository
- Create a feature branch
git checkout -b feature/amazing-feature
- Commit your changes
git commit -m 'Add amazing feature' - Push to the branch
git push origin feature/amazing-feature
- Open a Pull Request
- Follow TypeScript best practices
- Use ESLint configuration provided
- Write meaningful commit messages
- Test your changes thoroughly
- Update documentation if needed
- Google Gemini AI for powerful question generation
- shadcn ui for excellent accessibility-focused components
- NextAuth.js for seamless authentication
- Vercel for reliable hosting platform
- Quiz generation may occasionally timeout with very complex topics
- Theme switching might require a page refresh in some browsers
- Add more question types (True/False, Fill-in-the-blank)
- Implement spaced repetition algorithm
- Add collaborative quiz features
- Mobile app development
- Advanced analytics and insights
Quizium is licensed under
CC BY-NC-SA 4.0.
- ✅ Free for personal, educational, and non-profit use
- ✅ Open for contributions and improvements
- ❌ No commercial use without permission
Commercial Licensing
Contact [frank2006x@gmail.com] for commercial licensing inquiries.
If you encounter any issues or have questions:
- GitHub Issues: Create an issue
- Live Demo: Try Quizium
Made with ❤️ by Frank2006x
⭐ Star this repository if you found it helpful!