# push-pray/quizzer architecture

> Architecture diagram of the GitHub repository push-pray/quizzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/push-pray/quizzer
- Repository: https://github.com/push-pray/quizzer

## Overview

1. **Overall shape**
   - This is a single monorepo with two main runtime pieces: a **Spring Boot backend** in `src/main/java` and a **React + TypeScript frontend** under `src/main/resources/Quizz`.
   - In development, the frontend runs as a separate Vite app; in deployment, it is packaged alongside the backend and served from the same codebase.

2. **Backend boundary**
   - The backend exposes the application’s core quiz functionality through REST controllers in `com.example.quizzer.RESTController`.
   - Main API areas are **categories, quizzes, questions, and reviews**. The README also documents answer submission endpoints used by the quiz-taking flow.

3. **Layered backend architecture**
   - The backend follows a standard Spring layering:
     - **model/**: JPA entities such as `Category`, `Quizz`, `Question`, `Review`, `User`
     - **repository/**: Spring Data JPA persistence interfaces
     - **service/**: business logic and transaction orchestration
     - **RESTController/**: HTTP entry points
     - **DTO/** and **mapper/**: API payload shaping and entity-to-DTO conversion via MapStruct

4. **Core data flow**
   - Requests come from the frontend to a REST controller.
   - The controller delegates to a service.
   - The service reads/writes entities through repositories.
   - Responses are usually returned as DTOs rather than raw entities, which keeps the API contract separate from persistence structure.

5. **Domain model**
   - The central business object is the **quiz** (`Quizz` in code), which belongs to a **category**, contains **questions**, and can have **reviews**.
   - `User` exists as a model, though the repo tree does not show a dedicated auth subsystem.
   - The README’s ER diagram matches this: `Category -> Quizz -> Question/Review`.

6. **Question and quiz composition**
   - `Question` is a key entity for both quiz creation and quiz-taking.
   - The DTO set includes `QuestionDTO`, `QuestionInfoDTO`, `QuestionResultDTO`, `AnswerResultDTO`, `OptionDTO`, and quiz/teacher info DTOs, which suggests the system distinguishes:
     - edit-time quiz/question representations
     - student-facing quiz delivery
     - result and grading views
   - Mappers (`QuestionMapper`, `QuizzMapper`) bridge these representations.

7. **Frontend structure**
   - The frontend is organized by role:
     - `TeacherDashboard/` for creating and editing quizzes, questions, and categories
     - `StudentDashboard/` for browsing published quizzes, answering questions, and reviewing results
   - The app entry points are `main.tsx` and `App.tsx`, with shared API helper files such as `quizzapi.ts`, `questionapi.ts`, `reviewapi.ts`, and `categoryapi.ts`.

8. **Frontend-to-backend interaction**
   - The React app does not appear to own business logic; it is primarily a presentation layer that calls backend REST APIs.
   - Separate API helper modules encapsulate HTTP access, which keeps components focused on UI state and navigation.
   - The frontend routes described in the README map directly to quiz management and quiz-taking screens.

9. **Seed data and startup behavior**
   - `SampleDataService` initializes sample quizzes/questions at startup, which is important for local development and demo usage.
   - This means the backend has a built-in bootstrap path for initial content rather than depending on manual database seeding.

10. **Persistence and environments**
   - Local development uses **H2 in-memory database**.
   - Production is configured for **PostgreSQL** and there is a separate `application-rahti.properties`, indicating deployment-specific configuration.
   - The repository also includes a `Dockerfile`, so containerized deployment is part of the architecture.

11. **Testing boundary**
   - Tests are focused on REST behavior and run against H2 in `src/test/resources`.
   - The test suite includes controller tests for categories, questions, quizzes, and answer flow, which suggests the primary verification strategy is API-level integration testing rather than isolated unit tests.

12. **Diagramming takeaway**
   - If you draw the architecture, the clearest boundaries are:
     - **React UI** on top
     - **REST API layer** in the Spring Boot app
     - **service + repository + JPA entity layers** in the backend
     - **H2/PostgreSQL** as persistence
     - **sample data bootstrapping** as a startup-only path
     - **tests** as a separate verification track against the API and in-memory DB

Main entry points: [`src/main/java/com/example/quizzer/RESTController`](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/RESTController) (REST API), [`src/main/java/com/example/quizzer/repository`](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/repository) (Repositories), [`src/main/resources/Quizz/src/main.tsx`](https://github.com/push-pray/quizzer/blob/main/src/main/resources/Quizz/src/main.tsx) (React app), [`src/test/java/com/example/quizzer`](https://github.com/push-pray/quizzer/tree/main/src/test/java/com/example/quizzer) (API tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_app(("Quizzer app<br/>Spring Boot entrypoint"))
  node_controllers["REST API<br/>HTTP controllers"]
  node_services["Services<br/>business layer"]
  node_repositories["Repositories<br/>JPA persistence"]
  node_models[("Domain model<br/>JPA entities")]
  node_dtos["DTOs<br/>API payloads"]
  node_mappers{{"Mappers<br/>MapStruct mapping"}}
  node_seed["Sample data<br/>startup seeding"]
end

subgraph group_frontend["Frontend"]
  node_uiapp(("React app<br/>Vite frontend<br/>[main.tsx]"))
  node_teacher["Teacher UI<br/>authoring screens"]
  node_student["Student UI<br/>taking screens"]
  node_apihelpers{{"API clients<br/>HTTP helpers"}}
end

subgraph group_infra["Runtime"]
  node_build["Packaging<br/>deploy config"]
  node_config["App config<br/>Spring config"]
end

subgraph group_tests["Tests"]
  node_app_tests["API tests<br/>REST tests"]
  node_test_cfg["Test config<br/>H2 config"]
end

node_app -->|"exposes"| node_controllers
node_controllers -->|"delegates"| node_services
node_services -->|"reads/writes"| node_repositories
node_repositories -->|"maps"| node_models
node_services -->|"returns"| node_dtos
node_mappers -->|"converts"| node_models
node_mappers -->|"converts"| node_dtos
node_controllers -->|"uses"| node_mappers
node_seed -->|"initializes"| node_repositories
node_seed -->|"creates"| node_models
node_uiapp -->|"calls"| node_apihelpers
node_apihelpers -->|"requests"| node_controllers
node_uiapp -->|"renders"| node_teacher
node_uiapp -->|"renders"| node_student
node_build -->|"packages"| node_config
node_app_tests -->|"verifies"| node_controllers
node_app_tests -->|"runs with"| node_test_cfg
node_app_tests -.->|"covers"| node_repositories

click node_app "https://github.com/push-pray/quizzer/blob/main/src/main/java/com/example/quizzer/QuizzerApplication.java"
click node_controllers "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/RESTController"
click node_services "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/service"
click node_repositories "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/repository"
click node_models "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/model"
click node_dtos "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/DTO"
click node_mappers "https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/mapper"
click node_seed "https://github.com/push-pray/quizzer/blob/main/src/main/java/com/example/quizzer/SampleDataService.java"
click node_uiapp "https://github.com/push-pray/quizzer/blob/main/src/main/resources/Quizz/src/main.tsx"
click node_teacher "https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src/components/TeacherDashboard"
click node_student "https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src/components/StudentDashboard"
click node_apihelpers "https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src"
click node_build "https://github.com/push-pray/quizzer/tree/main/Dockerfile"
click node_config "https://github.com/push-pray/quizzer/tree/main/src/main/resources"
click node_app_tests "https://github.com/push-pray/quizzer/tree/main/src/test/java/com/example/quizzer"
click node_test_cfg "https://github.com/push-pray/quizzer/blob/main/src/test/resources/application.properties"

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_app,node_controllers,node_services,node_repositories,node_models,node_dtos,node_mappers,node_seed toneBlue
class node_uiapp,node_teacher,node_student,node_apihelpers toneAmber
class node_build,node_config toneMint
class node_app_tests,node_test_cfg toneRose
```

## Components

### Backend

Spring Boot API, domain, and persistence layers

- [Quizzer app](https://github.com/push-pray/quizzer/blob/main/src/main/java/com/example/quizzer/QuizzerApplication.java): Spring Boot entrypoint · Main backend application bootstrap · `src/main/java/com/example/quizzer/QuizzerApplication.java`
- [REST API](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/RESTController): HTTP controllers · Quiz, category, question, and review endpoints · `src/main/java/com/example/quizzer/RESTController`
- [Services](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/service): business layer · Transaction and orchestration logic · `src/main/java/com/example/quizzer/service`
- [Repositories](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/repository): JPA persistence · Spring Data repositories for domain entities · `src/main/java/com/example/quizzer/repository`
- [Domain model](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/model): JPA entities · Category, Quizz, Question, Review, User · `src/main/java/com/example/quizzer/model`
- [DTOs](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/DTO): API payloads · Request and response shapes for quiz flows · `src/main/java/com/example/quizzer/DTO`
- [Mappers](https://github.com/push-pray/quizzer/tree/main/src/main/java/com/example/quizzer/mapper): MapStruct mapping · Entity-to-DTO conversion for quizzes and questions · `src/main/java/com/example/quizzer/mapper`
- [Sample data](https://github.com/push-pray/quizzer/blob/main/src/main/java/com/example/quizzer/SampleDataService.java): startup seeding · Bootstraps demo quizzes and questions on startup · `src/main/java/com/example/quizzer/SampleDataService.java`

### Frontend

React + TypeScript quiz UI

- [React app](https://github.com/push-pray/quizzer/blob/main/src/main/resources/Quizz/src/main.tsx): Vite frontend · Frontend entry and application shell · `src/main/resources/Quizz/src/main.tsx`
- [Teacher UI](https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src/components/TeacherDashboard): authoring screens · Quiz, question, and category management views · `src/main/resources/Quizz/src/components/TeacherDashboard`
- [Student UI](https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src/components/StudentDashboard): taking screens · Browsing, answering, and review views · `src/main/resources/Quizz/src/components/StudentDashboard`
- [API clients](https://github.com/push-pray/quizzer/tree/main/src/main/resources/Quizz/src): HTTP helpers · Frontend modules for category, quiz, question, and review requests · `src/main/resources/Quizz/src`

### Runtime

Packaging and deployment configuration

- [Packaging](https://github.com/push-pray/quizzer/tree/main/Dockerfile): deploy config · Container and environment-specific Spring configuration · `Dockerfile`
- [App config](https://github.com/push-pray/quizzer/tree/main/src/main/resources): Spring config · Local and deployment property sets · `src/main/resources`

### Tests

API-level verification against in-memory DB

- [API tests](https://github.com/push-pray/quizzer/tree/main/src/test/java/com/example/quizzer): REST tests · Controller tests for categories, quizzes, questions, and answers · `src/test/java/com/example/quizzer`
- [Test config](https://github.com/push-pray/quizzer/blob/main/src/test/resources/application.properties): H2 config · Test-only application properties for in-memory execution · `src/test/resources/application.properties`

## Connections

- Quizzer app → REST API: exposes · Application wires REST entry points
- REST API → Services: delegates · Controllers call service methods
- Services → Repositories: reads/writes · Business logic persists via repositories
- Repositories → Domain model: maps · Repositories manage entity state
- Services → DTOs: returns · Services shape API data through DTOs
- Mappers → Domain model: converts · Maps entities into transfer objects
- Mappers → DTOs: converts · Produces API payload shapes
- REST API → Mappers: uses · Controllers rely on mapping for responses
- Sample data → Repositories: initializes · Loads starter content at startup
- Sample data → Domain model: creates · Seeds demo domain records
- React app → API clients: calls · UI uses request helpers for backend access
- API clients → REST API: requests · Frontend talks to REST endpoints
- React app → Teacher UI: renders · Teacher dashboard screens
- React app → Student UI: renders · Student dashboard screens
- Packaging → App config: packages · Containerized deployment uses Spring config
- API tests → REST API: verifies · Tests exercise REST behavior
- API tests → Test config: runs with · Tests use in-memory database config
- API tests → Repositories: covers · API tests implicitly validate persistence flows