# dev050x/ai-quizzer-backend architecture

> Architecture diagram of the GitHub repository dev050x/ai-quizzer-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dev050x/ai-quizzer-backend
- Repository: https://github.com/dev050x/ai-quizzer-backend

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        SignUp["POST /api/sign-up"]:::api
        SignIn["POST /api/sign-in"]:::api
        VerifyCode["POST /api/verify-code"]:::api
        GenerateQuiz["POST /api/generate-quiz"]:::api
        GetHistory["GET /api/get-history"]:::api
        RetrieveQuiz["GET /api/quizzes/[quizId]"]:::api
        RetrieveQuestion["GET /api/quizzes/[quizId]/questions/[questionId]"]:::api
        RetryQuiz["POST /api/retry-quiz"]:::api
        Submission["POST /api/submission"]:::api
        SendReport["POST /api/send-report/[quizId]"]:::api
        HealthCheck["GET /api/health"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        GenQ["generateQuestions.ts"]:::service
        SendAnalytic["sendAnalyticEmail.ts"]:::service
        SendVerification["sendVerificationEmail.ts"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DBConn["dbConnect.ts"]:::service
        RedisClient["redis.ts"]:::service
        subgraph "Models"
            direction TB
            UserModel["User.ts"]:::service
            QuizModel["Quiz.ts"]:::service
            SubmissionModel["Submission.ts"]:::service
        end
        MongoDB[(MongoDB)]:::db
        RedisCache[(Redis)]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI[("OpenAI API")]:::externalApi
        Resend[("Resend API")]:::externalApi
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        Docker["Docker Container"]:::infra
        AWS["AWS EC2"]:::infra
    end

    %% Flows
    Client -->|calls| SignUp
    Client --> SignIn
    Client --> VerifyCode
    Client --> GenerateQuiz
    Client --> GetHistory
    Client --> RetrieveQuiz
    Client --> RetrieveQuestion
    Client --> RetryQuiz
    Client --> Submission
    Client --> SendReport
    Client --> HealthCheck

    %% Auth Flow
    SignUp -->|uses| ServiceLayerAuth[/"Auth Module"/]:::service
    SignIn --> ServiceLayerAuth
    VerifyCode --> ServiceLayerAuth

    %% Quiz Generation Flow
    GenerateQuiz --> GenQ
    GenQ -->|calls| OpenAI
    GenQ --> RedisClient
    GenQ --> DBConn

    %% History Flow
    GetHistory --> RedisClient
    RedisClient --> RedisCache
    GetHistory --> DBConn

    %% Retrieval Flow
    RetrieveQuiz --> DBConn
    RetrieveQuestion --> DBConn

    %% Retry Flow
    RetryQuiz --> GenQ

    %% Submission Flow
    Submission --> GenQ
    Submission --> DBConn
    Submission --> RedisClient
    GenQ -->|scoring| OpenAI

    %% Reporting Flow
    SendReport --> SendAnalytic
    SendReport --> SendVerification
    SendAnalytic --> Resend
    SendVerification --> Resend

    %% Health Check
    HealthCheck -->|ping| DBConn
    HealthCheck -->|ping| RedisClient

    %% Data Connectors
    DBConn --> MongoDB
    RedisClient --> RedisCache

    %% Infrastructure
    SignUp --> Docker
    SignIn --> Docker
    GenerateQuiz --> Docker
    Docker --> AWS

    %% Click Events
    click SignUp "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/sign-up/route.ts"
    click SignIn "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/sign-in/route.ts"
    click VerifyCode "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/verify-code/route.ts"
    click GenerateQuiz "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/generate-quiz/route.ts"
    click GetHistory "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/get-history/route.ts"
    click RetrieveQuiz "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/quizzes/[quizId]/route.ts"
    click RetrieveQuestion "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/quizzes/[quizId]/questions/[questionId]/route.ts"
    click RetryQuiz "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/retry-quiz/route.ts"
    click Submission "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/submission/route.ts"
    click SendReport "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/send-report/[quizId]/route.ts"
    click HealthCheck "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/app/api/health/route.ts"
    click GenQ "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/helpers/generateQuestions.ts"
    click SendAnalytic "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/helpers/sendAnalyticEmail.ts"
    click SendVerification "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/helpers/sendVerificationEmail.ts"
    click DBConn "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/lib/dbConnect.ts"
    click RedisClient "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/lib/redis.ts"
    click UserModel "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/model/User.ts"
    click QuizModel "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/model/Quiz.ts"
    click SubmissionModel "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/model/Submission.ts"
    click Resend "https://github.com/dev050x/ai-quizzer-backend/blob/main/src/lib/resend.ts"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0052CC,color:#000
    classDef service fill:#E8F0FE,stroke:#1A73E8,color:#000
    classDef db fill:#DFF7DF,stroke:#0F9D58,color:#000
    classDef externalApi fill:#FFE7D9,stroke:#E37400,color:#000
    classDef infra fill:#F0F0F0,stroke:#888888,color:#000
    classDef external fill:#FFFFFF,stroke:#AAAAAA,color:#000,lineStyle:dash
    class ServiceLayerAuth service
    class ServiceLayerAuth fill:#E8F0FE,stroke:#1A73E8,color:#000
```
