# daniloneto/quiz architecture

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

- Interactive diagram: https://gitdiagram.com/daniloneto/quiz
- Repository: https://github.com/daniloneto/quiz

## Overview

Step 1: Identify the project type and purpose
- QuizGPT is a backend‐only service (using Next.js API Routes) that exposes a RESTful API for:
- User authentication & profile management
- Generating quizzes/exams via OpenAI GPT
- Persisting quizzes, exams, quiz results, profiles in MongoDB
- Rate limiting (Redis or in-memory) and logging

Step 2: Analyze the file structure
- src/pages/api/v1: API routes → HTTP controllers / route handlers
- src/controllers: thin controllers for upload / GPT integration
- src/application/usecases: business‐logic layer (Use Cases)
- src/domain/entities & services & repositories: core domain model
- src/infrastructure: concrete implementations (Mongo repositories, Argon2, JWT, Email, VerificationToken)
- src/lib: cross‐cutting middleware (auth, rate-limiter, validators)
- src/config: environment/configuration modules (DB connection, logger, OpenAI config)

Step 3: Examine README for additional insights
- Tech stack: Next.js API (Node.js), MongoDB, JWT, Argon2, Upstash Redis, Winston + winston-mongodb, OpenAI GPT
- Key features: authentication, quiz generation, storage, backups

a. Main components
1. Clients (Web/Mobile or CLI)
2. API Gateway / Next.js server (pages/api)
3. HTTP Controllers & Middleware
4. Application Layer (Use Cases)
5. Domain Layer (Entities, Domain Services, Repository Interfaces)
6. Infrastructure Layer (MongoDB Repositories, Email Service, JWT Service, Password Service, Verification Token Service)
7. External Services:
- MongoDB
- Redis (rate limiting)
- OpenAI GPT API
- Email SMTP/Provider
- Winston-MongoDB for log persistence
b. Relationships & data flow
1. Client → Next.js API Route → Middleware (auth / rate limiter / validation)
2. Route Handler → Controller → injects and calls Use Case
3. Use Case orchestrates Domain Entities & Domain Services → invokes Repository Interfaces
4. Repository Interface bound to Infrastructure implementation
5. Infrastructure implementation → Database / External Service
6. Use Case returns response → Controller → HTTP Response to Client
c. Architectural patterns and principles
- Onion / Hexagonal Architecture:
- Outermost: Controllers & Framework (Next.js)
- Application Layer: Use Cases (business “verbs”)
- Core Domain: Entities & Domain Services (business rules)
- Infrastructure: Adapters implementing repository & external API interfaces
- Dependency Inversion: Application & Domain depend on abstract interfaces; infra implements them
- Single Responsibility & Separation of Concerns at each layer
d. Key technologies and libraries
- Next.js API Routes, Node.js
- TypeScript
- MongoDB via official driver or Mongoose-style repository
- Redis or in-memory store for rate limiting
- Winston + winston-mongodb for logging
- Argon2 for password hashing
- JSON Web Tokens for authentication
- OpenAI SDK for GPT integration

- API only nature: no UI layer included
- GPT integration adapter under Infrastructure → OpenAI Service
- Optional branches for Redis vs in-memory rate limiter
- Verify-Email and Password-Reset flows via VerificationTokenService & EmailService

Step 6: Diagramming guidelines
- Blue: API Gateway & Controllers
- Green: Application & Domain layers
- Orange: Infrastructure adapters
- Gray: External systems (MongoDB, Redis, OpenAI, Email)
Client → API Gateway → Controllers → Use Cases → Repos/Services → External systems
- Middleware (auth, rate limiter, validators) around the Controller ingress path
- Flows (e.g., “GenerateQuizUseCase calls OpenAIService → returns questions”)

Final tips:
- Layers distinctly—do not lump domain with infrastructure
- Call out critical adapters (MongoAuthRepository, Argon2PasswordService, JwtService, EmailService, VerificationTokenService)
- Test suite structure at the bottom or aside to show coverage targets

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::external
    ApiGateway["Next.js API\n(src/pages/api/v1)"]:::api
    Middleware["Middleware\n(auth, rateLimiter, validators)"]:::api

    subgraph Controllers
        UploadController["uploadController.ts"]:::controller
        AuthRoutes["Auth Routes"]:::controller
        ExamsRoutes["Exams Routes"]:::controller
        QuizRoutes["Quiz Routes"]:::controller
        ProfileRoutes["Profile Routes"]:::controller
        BackupRoute["Backup Create\n(create.ts)"]:::controller
        GPTIntegrationRoute["GPT Integration Route\ngpt-integration.ts"]:::controller
    end

    UseCases["Use Cases\n(src/application/usecases)"]:::app
    Entities["Entities\n(src/domain/entities)"]:::domain
    RepoInterfaces["Repository Interfaces\n(src/domain/repositories)"]:::domain
    DomainServices["Domain Services\n(src/domain/services)"]:::domain

    DBRepos["Database Repositories\n(src/infrastructure/database)"]:::infra
    InfraServices["Services Adapters\n(src/infrastructure/services)"]:::infra

    MongoDB["MongoDB"]:::external
    Redis["Redis\n(rate limiter store)"]:::external
    OpenAI["OpenAI GPT API"]:::external
    Email["Email SMTP"]:::external
    WinstonDB["Winston-MongoDB"]:::external

    Client --> ApiGateway --> Middleware
    Middleware --> UploadController
    Middleware --> AuthRoutes
    Middleware --> ExamsRoutes
    Middleware --> QuizRoutes
    Middleware --> ProfileRoutes
    Middleware --> BackupRoute
    Middleware --> GPTIntegrationRoute

    UploadController --> UseCases
    AuthRoutes --> UseCases
    ExamsRoutes --> UseCases
    QuizRoutes --> UseCases
    ProfileRoutes --> UseCases
    BackupRoute --> UseCases
    GPTIntegrationRoute --> UseCases

    UseCases --> Entities
    UseCases --> RepoInterfaces
    UseCases --> DomainServices

    RepoInterfaces --> DBRepos
    DomainServices --> InfraServices

    DBRepos --> MongoDB
    InfraServices --> Email
    InfraServices --> WinstonDB

    Middleware --> Redis
    UseCases --> OpenAI

    click ApiGateway "https://github.com/daniloneto/quiz/tree/main/src/pages/api/v1"
    click UploadController "https://github.com/daniloneto/quiz/blob/main/src/controllers/uploadController.ts"
    click AuthRoutes "https://github.com/daniloneto/quiz/tree/main/src/pages/api/v1/auth"
    click ExamsRoutes "https://github.com/daniloneto/quiz/tree/main/src/pages/api/v1/exams"
    click QuizRoutes "https://github.com/daniloneto/quiz/tree/main/src/pages/api/v1/quiz"
    click ProfileRoutes "https://github.com/daniloneto/quiz/tree/main/src/pages/api/v1/profile"
    click BackupRoute "https://github.com/daniloneto/quiz/blob/main/src/pages/api/v1/backup/create.ts"
    click GPTIntegrationRoute "https://github.com/daniloneto/quiz/blob/main/src/pages/api/v1/upload/gpt-integration.ts"
    click Middleware "https://github.com/daniloneto/quiz/blob/main/src/lib/middleware.ts"
    click UseCases "https://github.com/daniloneto/quiz/tree/main/src/application/usecases"
    click Entities "https://github.com/daniloneto/quiz/tree/main/src/domain/entities"
    click RepoInterfaces "https://github.com/daniloneto/quiz/tree/main/src/domain/repositories"
    click DomainServices "https://github.com/daniloneto/quiz/tree/main/src/domain/services"
    click DBRepos "https://github.com/daniloneto/quiz/tree/main/src/infrastructure/database"
    click InfraServices "https://github.com/daniloneto/quiz/tree/main/src/infrastructure/services"

    classDef api fill:#D0E8FF,stroke:#0059B2,color:#000;
    classDef controller fill:#A9D6FF,stroke:#0059B2,color:#000;
    classDef middleware fill:#D0E8FF,stroke:#0059B2,color:#000;
    classDef app fill:#DFF7D8,stroke:#2E7D32,color:#000;
    classDef domain fill:#E6F2D9,stroke:#558B2F,color:#000;
    classDef infra fill:#FFE0B2,stroke:#FF8F00,color:#000;
    classDef external fill:#F0F0F0,stroke:#666,color:#000;
```
