How daniloneto/quiz works
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