# soufiane2204/quiz-api architecture

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

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

## Overview

Quiz API accepts validated quiz-generation requests, obtains AI-generated questions, validates and persists them, then exposes answer-hidden quizzes. Submission loads a quiz, scores ordered answers, saves an attempt, and returns corrections; other endpoints list quizzes and prior attempts. The service is the business-flow layer between HTTP, AI, repositories, and domain entities. README documents Claude by default and Ollama as an optional provider; source excerpts do not show the provider wiring, so those integration links are marked unverified.

Main entry points: [`src/main/java/com/soufiane/quizapi/service/QuizService.java`](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/service/QuizService.java) (Quiz workflows), [`src/main/java/com/soufiane/quizapi/dto`](https://github.com/soufiane2204/quiz-api/tree/main/src/main/java/com/soufiane/quizapi/dto) (Requests and responses), [`src/main/java/com/soufiane/quizapi/controller/QuizController.java`](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/controller/QuizController.java) (Quiz endpoints), [`src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java`](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java) (Claude generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["REST API"]
  node_controller["Quiz endpoints"]
  node_dto["Requests and responses"]
  node_errors["Error mapping"]
end

subgraph group_logic["Quiz workflows"]
  node_service["Quiz workflows<br/>[QuizService.java]"]
  node_models["Quiz domain"]
end

subgraph group_ai["AI generation"]
  node_generator["Generator contract<br/>[QuizGenerator.java]"]
  node_claude["Claude generator"]
  node_ollama["Ollama profile"]
end

subgraph group_data["Persistence"]
  node_quizrepo["Quiz repository"]
  node_attemptrepo["Attempt repository"]
end

node_user(("API client"))
node_mysql[("MySQL database")]
node_anthropic{{"Anthropic API"}}
node_ollamasvc{{"Ollama service"}}

node_user -->|"calls endpoints"| node_controller
node_controller -->|"delegates to"| node_service
node_user -->|"sends requests"| node_dto
node_controller -->|"returns DTOs"| node_dto
node_service -->|"builds responses"| node_dto
node_service -->|"requests questions"| node_generator
node_claude -->|"implements contract"| node_generator
node_claude -.->|"calls model"| node_anthropic
node_ollama -.->|"configures provider"| node_ollamasvc
node_service -->|"reads and saves quizzes"| node_quizrepo
node_service -->|"reads and saves attempts"| node_attemptrepo
node_service -->|"scores and maps"| node_models
node_quizrepo -.->|"persists quizzes"| node_mysql
node_attemptrepo -.->|"persists attempts"| node_mysql
node_service -->|"raises domain errors"| node_errors
node_errors -->|"formats errors"| node_dto

click node_controller "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/controller/QuizController.java"
click node_dto "https://github.com/soufiane2204/quiz-api/tree/main/src/main/java/com/soufiane/quizapi/dto"
click node_errors "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/exception/GlobalExceptionHandler.java"
click node_service "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/service/QuizService.java"
click node_models "https://github.com/soufiane2204/quiz-api/tree/main/src/main/java/com/soufiane/quizapi/model"
click node_generator "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/ai/QuizGenerator.java"
click node_claude "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java"
click node_ollama "https://github.com/soufiane2204/quiz-api/blob/main/src/main/resources/application-ollama.properties"
click node_quizrepo "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/repository/QuizRepository.java"
click node_attemptrepo "https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/repository/AttemptRepository.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_controller,node_dto,node_errors,node_user toneBlue
class node_service,node_models,node_mysql toneAmber
class node_generator,node_claude,node_ollama,node_anthropic toneMint
class node_quizrepo,node_attemptrepo toneRose
class node_ollamasvc toneIndigo
```

## Components

### REST API

- [Quiz endpoints](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/controller/QuizController.java): `src/main/java/com/soufiane/quizapi/controller/QuizController.java`
- [Requests and responses](https://github.com/soufiane2204/quiz-api/tree/main/src/main/java/com/soufiane/quizapi/dto): `src/main/java/com/soufiane/quizapi/dto`
- [Error mapping](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/exception/GlobalExceptionHandler.java): `src/main/java/com/soufiane/quizapi/exception/GlobalExceptionHandler.java`

### Quiz workflows

- [Quiz workflows](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/service/QuizService.java): `src/main/java/com/soufiane/quizapi/service/QuizService.java`
- [Quiz domain](https://github.com/soufiane2204/quiz-api/tree/main/src/main/java/com/soufiane/quizapi/model): `src/main/java/com/soufiane/quizapi/model`

### AI generation

- [Generator contract](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/ai/QuizGenerator.java): `src/main/java/com/soufiane/quizapi/ai/QuizGenerator.java`
- [Claude generator](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java): `src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java`
- [Ollama profile](https://github.com/soufiane2204/quiz-api/blob/main/src/main/resources/application-ollama.properties): `src/main/resources/application-ollama.properties`

### Persistence

- [Quiz repository](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/repository/QuizRepository.java): `src/main/java/com/soufiane/quizapi/repository/QuizRepository.java`
- [Attempt repository](https://github.com/soufiane2204/quiz-api/blob/main/src/main/java/com/soufiane/quizapi/repository/AttemptRepository.java): `src/main/java/com/soufiane/quizapi/repository/AttemptRepository.java`

### Other components

- **API client**
- **MySQL database**
- **Anthropic API**
- **Ollama service**

## Connections

- API client → Quiz endpoints: calls endpoints (evidence: `src/main/java/com/soufiane/quizapi/controller/QuizController.java`)
- Quiz endpoints → Quiz workflows: delegates to (evidence: `src/main/java/com/soufiane/quizapi/controller/QuizController.java`)
- API client → Requests and responses: sends requests (evidence: `README.md`)
- Quiz endpoints → Requests and responses: returns DTOs (evidence: `src/main/java/com/soufiane/quizapi/controller/QuizController.java`)
- Quiz workflows → Requests and responses: builds responses (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Quiz workflows → Generator contract: requests questions (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Claude generator → Generator contract: implements contract (evidence: `src/main/java/com/soufiane/quizapi/ai/ClaudeQuizGenerator.java`)
- Claude generator → Anthropic API: calls model (evidence: `README.md`)
- Ollama profile → Ollama service: configures provider (evidence: `README.md`)
- Quiz workflows → Quiz repository: reads and saves quizzes (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Quiz workflows → Attempt repository: reads and saves attempts (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Quiz workflows → Quiz domain: scores and maps (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Quiz repository → MySQL database: persists quizzes (evidence: `README.md`)
- Attempt repository → MySQL database: persists attempts (evidence: `README.md`)
- Quiz workflows → Error mapping: raises domain errors (evidence: `src/main/java/com/soufiane/quizapi/service/QuizService.java`)
- Error mapping → Requests and responses: formats errors (evidence: `src/main/java/com/soufiane/quizapi/exception/GlobalExceptionHandler.java`)
