How dev050x/ai-quizzer-backend works
Project Type and Purpose
• Type: Backend microservice
• Framework: Next.js (App Router)
• Language: TypeScript
• Purpose: Expose REST-style API endpoints for AI-driven quiz generation, submission, evaluation, and reporting. It also handles authentication, caching, and email notifications.
File Structure
• Top-level files: Dockerfile, next.config.ts, tsconfig.json, .dockerignore, .eslintrc.json, .gitignore
• src/app/api: All HTTP route handlers (authentication, quiz generation, quiz retrieval/history, submissions, health checks, email reporting, etc.)
• src/helpers: Business-logic utilities (generate AI questions, send analytic and verification emails)
• src/lib: Infrastructure glue (MongoDB connector, Redis client, Resend API wrapper)
• src/model: Mongoose or Mongo schema definitions for User, Quiz, Submission
• root/emails: React-style email templates
• src/types: Shared TypeScript interfaces
Extract Architectural Insights from the README
• JWT authentication with jose + bcrypt for password hashing
• MongoDB primary datastore
• Upstash Redis as a caching layer for quiz/response data
• OpenAI API for AI-powered quiz creation and evaluation
• Resend API for email notifications
• Containerized via Docker, deployed on AWS EC2
Main Components and Their Responsibilities
1. API Gateway / Next.js App Router
– Exposes REST endpoints under /api/*
– Handles routing, input validation, error handling
2. Authentication Module
– Sign-up, sign-in, JWT issuance, code verification
3. Business Logic Layer
– Quiz generation (calls OpenAI)
– Submission evaluation (calls OpenAI or local logic)
– History retrieval with optional filters
– Retry/quizzes workflow
4. Data Access Layer
– MongoDB (user, quiz, submission collections via src/model)
– Redis caching (Upstash)
5. Notification Service
– Email builders (React templates in root/emails)
– Resend API integration
6. External Services
– OpenAI API
– Resend (email) API
7. Infrastructure
– Docker container
– AWS EC2 hosting
Relationships and Data Flows
• Client → Next.js API
• API → Auth Module → JWT
• API → Business Logic →
– MongoDB (read/write)
– Redis (cache read/write)
– OpenAI (quiz generation & scoring)
• Business Logic → Notification Service → Resend API → Email recipients
• Health checks → internal endpoint
Architectural Patterns and Principles
• Layered / Clean Architecture:
– Controllers (route handlers) → Services (helpers) → Repositories (lib/dbConnect, lib/redis) → Models
• Microservice style: single responsibility (quiz service + auth + notifications in one container)
• Stateless API (state kept in MongoDB/Redis, auth via JWT)
• Externalize side-effects (emails, AI calls) behind well-defined interfaces