Quizzard 🧙‍♂️

A web application for creating and participating in quizzes, allowing users to test their knowledge on various topics and track their progress.

🌐 Live Demo

• FrontEnd

📋 Table of Contents

• Features
• Tech Stack
• Project Structure
• Getting Started
• Docker & Deployment
• API Endpoints
• Contributing

✨ Features

• User Authentication: Secure signup and login functionality
• Quiz Creation: Create custom quizzes with multiple question types
• AI Quiz Generator: Generate quizzes instantly using Google Gemini 2.5 Flash API - specify topic, question count, and difficulty level, then customize before creating
• Quiz Participation: Take quizzes created by others
• Progress Tracking: Monitor performance and view scores
• Leaderboards: See where you stand compared to others
• Admin Panel: Manage quizzes and users (admin access only)

🛠️ Tech Stack

Frontend

• React.js: JavaScript library for building user interfaces
• Vite: Next-generation frontend tooling
• React Router: For navigation and routing
• CSS3: For styling components

Backend

• Node.js: JavaScript runtime environment
• Express.js: Web application framework
• MongoDB: NoSQL database for storing user and quiz data
• JWT Authentication: For secure user sessions

Tools & Services

• Git & GitHub: Version control and code hosting
• Vercel: Frontend deployment platform
• MongoDB Atlas: Cloud database service
• Google Gemini 2.5 Flash API: AI-powered quiz generation
• Proxmox: Self-hosted server infrastructure

📁 Project Structure

quizzard/
├── backend/              # Backend server code
│   ├── controller/       # Request handlers
│   ├── middleware/       # Express middlewares
│   ├── models/           # Database models
│   ├── routes/           # API routes
│   └── index.js          # Server entry point
│
├── frontend/             # Frontend React application
│   ├── public/           # Static assets
│   └── src/              # Source files
│       ├── api/          # API communication
│       ├── assets/       # Images and media
│       ├── Components/   # Reusable components
│       ├── context/      # React context providers
│       ├── utils/        # Utility functions
│       └── [features]/   # Feature-specific components

🚀 Getting Started

Prerequisites

• Node.js (v14 or later)
• npm or yarn
• MongoDB instance (local or Atlas)

Installation Options

Option 1: Local Development

Follow the installation steps below to run locally.

Backend Setup

# Navigate to backend directory
cd backend

# Install dependencies
npm install

# Create .env file with your environment variables
# Example:
# MONGODB_URI=mongodb://localhost:27017/quizzard
# JWT_SECRET=your_jwt_secret
# PORT=5000

# Start the server
npm start

Frontend Setup

# Navigate to frontend directory
cd frontend

# Install dependencies
npm install

# Create .env file with your environment variables
# Example:
# VITE_API_URL=http://localhost:5000/api

# Start the development server
npm run dev

Option 2: Docker & Coolify (Production)

For deploying on Proxmox using Coolify:

# See detailed guide in DOCKER_DEPLOYMENT.md
# Quick start with docker-compose for testing:
docker-compose up --build

See DOCKER_DEPLOYMENT.md for complete Docker and Coolify setup instructions.

� Docker & Deployment

This project includes production-ready Docker configurations for deploying on Coolify (Proxmox).

Quick Start with Docker Compose

# Clone and setup environment
cp .env.docker.example .env
# Edit .env with your configuration

# Build and run all services
docker-compose up --build

# Access the application
# Frontend: http://localhost
# Backend API: http://localhost:5000
# MongoDB: localhost:27017

Separate Container Deployment on Coolify

Build backend and frontend as separate containers:

# Backend
docker build -t quizzard-backend:latest ./backend

# Frontend
docker build -t quizzard-frontend:latest ./frontend

Then deploy each separately in Coolify with appropriate environment variables.

See full deployment guide →

�📡 API Endpoints

Authentication

• POST /api/auth/register - Register a new user
• POST /api/auth/login - Login user
• GET /api/auth/profile - Get user profile (authenticated)

Quizzes

• GET /api/quizzes - Get all quizzes
• GET /api/quizzes/:id - Get a specific quiz
• POST /api/quizzes - Create a new quiz (authenticated)

AI Quiz Generation

• POST /api/ai-quizzes/preview - Generate a quiz preview using Gemini AI (without saving)
• POST /api/ai-quizzes - Generate and save a quiz using Gemini AI
• PUT /api/quizzes/:id - Update a quiz (authenticated)
• DELETE /api/quizzes/:id - Delete a quiz (authenticated)

Quiz Attempts

• POST /api/quiz-attempts - Create a new quiz attempt
• GET /api/quiz-attempts/:quizId - Get attempts for a quiz
• GET /api/quiz-attempts/user - Get user's quiz attempts (authenticated)

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ by Utkarsh Sharma