AI Quizzer Microservice

An AI-powered quiz generation and evaluation microservice built with Node.js, Express, PostgreSQL, and Prisma.

Table of Contents

• Features
• Tech Stack
• Getting Started
• API Documentation
• Caching Strategy
• Database Schema
• Docker Deployment
• Security Considerations
• Contributing
• License
• Acknowledgments

Features

• Authentication:

  • User registration and login
  • JWT token-based authentication
  • Email verification for new accounts
  • Secure HTTP-only cookies for token storage

• Quiz Management:

  • Generate quizzes using AI (Google Gemini API)
  • Customize quizzes by grade, subject, difficulty, and number of questions
  • Submit answers for AI evaluation with detailed feedback
  • View quiz history with filtering options
  • Get AI-generated hints for challenging questions

• User Experience:

  • Personalized dashboard with quiz statistics
  • Email notifications with quiz results
  • AI-generated improvement suggestions
  • Performance tracking across subjects and time periods

• Performance Optimization:

  • Redis caching for faster response times
  • Strategic caching of expensive operations
  • Automated cache invalidation
  • Background cache cleanup

Tech Stack

• Backend: Node.js, Express
• Database: PostgreSQL with Prisma ORM
• Cache: Redis
• Authentication: JWT with HTTP-only cookies
• Email: Nodemailer
• AI: Google Gemini API
• Deployment: Docker, Docker Compose, Render

Getting Started

Prerequisites

• Node.js (v18+)
• PostgreSQL
• Redis
• API key for Google Gemini

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/ai-quizzer.git
   cd ai-quizzer

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env

   Then edit the .env file with your configuration. Required variables:

   # Server Configuration
   PORT=3000
   NODE_ENV=development
   
   # Database Configuration
   DATABASE_URL=postgresql://postgres:password@localhost:5432/aiquizzer
   
   # JWT Configuration
   JWT_SECRET=your_jwt_secret_key
   JWT_EXPIRES_IN=1d
   
   # Redis Configuration
   REDIS_URL=redis://localhost:6379
   
   # Email Configuration
   EMAIL_SERVICE=gmail
   EMAIL_USER=your_email@gmail.com
   EMAIL_PASSWORD=your_app_password
   
   # Google Gemini API
   GEMINI_API_KEY=your_gemini_api_key
   

4. Generate Prisma client:

   npx prisma generate

5. Run database migrations:

   npx prisma migrate dev

Running the Application

Development mode:

npm run dev

Production mode:

npm start

Docker Deployment

Local Deployment with Docker Compose

Build and run with Docker Compose:

docker-compose up -d

This will start both the application and PostgreSQL in containers.

Production Deployment

The application is deployed on Render using a Docker image hosted on Docker Hub.

Using the Public Docker Image

The public Docker image is available at harsh268/aiquizzer:latest.

Making Your Docker Image Private

To improve security by making your Docker image private:

1. Log in to Docker Hub:

   • Go to Docker Hub and sign in with your account
   • Navigate to your "aiquizzer" repository

2. Change repository visibility:

   • Click on the "Settings" tab within your repository
   • Scroll to find the "Visibility" section
   • Change from "Public" to "Private"
   • Save your changes

3. Update Render configuration for private image:

   • Log in to your Render dashboard
   • Go to your AI Quizzer service settings
   • Enable "Private Registry"
   • Enter your Docker Hub credentials
   • Save the changes

Building and Pushing Your Docker Image

Run the included PowerShell script:

.\push-docker-image.ps1

API Documentation

The application is live at: https://aiquizzer-4qc3.onrender.com

You can visit the live application using the link above.

It is deployed on Render, so it may spin down due to inactivity. Your first request can take some time.

Test Accounts

{
  "username": "Harsh",
  "email": "harshpatel17079@gmail.com",
  "password": "Patel@123"
}

The API is organized around RESTful principles. Below is a summary of the main endpoints:

Authentication Endpoints

• POST /api/v1/auth/register: Register a new user

  • Body: { "username": "user", "email": "user@example.com", "password": "password123" }

• GET /api/v1/auth/verify-email: Verify user email with token

  • Query: ?token=verification_token

  Currently, there is no frontend. You can set your app URL in the environment variables and match the path for the verification page, which should extract the token from params and call the backend API endpoint for verification.

• POST /api/v1/auth/login: Log in and receive authentication token

  • Body: { "email": "user@example.com", "password": "password123" }
  • Response includes HTTP-only cookie with JWT token

• POST /api/v1/auth/logout: Log out and clear authentication cookie

• POST /api/v1/auth/resend-verification: Resend email verification

User Endpoints

• GET /api/v1/users/profile: Get user profile information

• GET /api/v1/users/stats: Get user quiz statistics

  • Shows aggregated data on quiz performance

Quiz Endpoints

• POST /api/v1/quizzes/generate: Generate a new quiz

  • Body: { "grade": "5th", "subject": "Math", "numQuestions": 5, "maxScore": 100, "difficulty": "medium" }

• GET /api/v1/quizzes: Get all quizzes

  • Supports filtering by grade, subject, date range, score range
  • Supports pagination

• GET /api/v1/quizzes/:id: Get a specific quiz by ID

• POST /api/v1/quizzes/:id/submit: Submit answers for a quiz

  • Body: { "answers": { "questionId1": "answer1", "questionId2": "answer2" }, "sendEmail": true }
  • Returns score, feedback, and improvement suggestions

• GET /api/v1/quizzes/history: Get quiz attempt history

  • Supports filtering by grade, subject, score, date range
  • Supports pagination

• GET /api/v1/quizzes/attempts/:id: Get a specific quiz attempt

• GET /api/v1/quizzes/:id/questions/:questionId/hint: Get an AI-generated hint for a specific question

Caching Strategy

The application implements a strategic caching approach to optimize performance:

Cached Resources

1. Quiz Data:

   • Cache Key: quiz:{quizId}
   • TTL: 3600 seconds (1 hour)
   • Invalidated when: A new attempt is submitted

2. User Profile:

   • Cache Key: user:profile:{userId}
   • TTL: 1800 seconds (30 minutes)
   • Invalidated when: User creates a quiz or submits an attempt

3. User Statistics:

   • Cache Key: user:stats:{userId}
   • TTL: 900 seconds (15 minutes)
   • Invalidated when: User creates a quiz or submits an attempt

4. Question Hints:

   • Cache Key: hint:{quizId}:{questionId}
   • TTL: 3600 seconds (1 hour)
   • Automatic cleanup: Daily background job removes old hint caches

Cache Maintenance

• Automatic Invalidation: Caches are automatically cleared when underlying data changes
• Background Cleanup: A scheduled task runs daily to clean up stale hint caches
• TTL Strategy: Different TTLs based on data volatility and access patterns

Database Schema

The database is managed using Prisma ORM, with the schema defined in prisma/schema.prisma. The main models include:

• User: Stores user account information

  • Authentication details
  • Profile information
  • Email verification status

• Quiz: Stores quiz details

  • Subject, grade, difficulty
  • Questions array with various question types
  • Maximum possible score

• QuizAttempt: Stores quiz submissions

  • User answers
  • Score and feedback
  • Timestamps for tracking progress

Postman Collection

A Postman collection is included in the repository to help test the API:

1. Import postman_collection.json into Postman
2. Set up the environment variables:
   • baseUrl: Set to https://aiquizzer-4qc3.onrender.com for production or http://localhost:3000 for local testing
   • email: Your email address
   • password: Your password
3. Execute the requests in sequence:
   • First register or login to get an authentication token
   • The token will be automatically applied to subsequent requests
4. Follow the testing guide in postman_testing_guide.md for detailed steps

Security Considerations

The AI Quizzer application implements several security features:

Authentication and Authorization

• JWT tokens with HTTP-only cookies
• Password hashing using bcrypt
• Email verification for new accounts

Data Protection

• Input validation for all API endpoints

Docker Image Security

• Use environment variables for sensitive information instead of hardcoding
• Follow the principle of least privilege in container configurations
• Consider making Docker Hub repository private for production use
• Use Docker secrets for managing sensitive credentials

Acknowledgments

• Google Gemini API for AI quiz generation
• Prisma for database ORM
• Express for the web framework
• Redis for caching
• Docker for containerization