# lllnightlll/math-jackbox architecture

> Architecture diagram of the GitHub repository lllnightlll/math-jackbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lllnightlll/math-jackbox
- Repository: https://github.com/lllnightlll/math-jackbox

## Overview

math-jackbox is a real-time, multiplayer math quiz. Players register or join as guests, enter a lobby, ready up, answer timed questions, and receive match results and a global leaderboard. The sampled Java backend shows WebSocket message handling, game-state orchestration, and JPA repositories. The README contains only the project name, so frontend behavior and the Python tree’s role cannot be confirmed; those are omitted. Edges reflect sampled calls and references, with database persistence marked unverified.

Main entry points: [`src/main/java/com/quiz/backend/service/QuizService.java`](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/service/QuizService.java) (Quiz Service), [`src/main/java/com/quiz/backend/controller/QuizController.java`](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/controller/QuizController.java) (Quiz Controller), [`src/main/java/com/quiz/backend/repository/QuestionRepository.java`](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/QuestionRepository.java) (Question Repository), [`src/main/java/com/quiz/backend/repository/PlayerRepository.java`](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/PlayerRepository.java) (Player Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Realtime Interface"]
  node_controller["Quiz Controller"]
  node_messages["Message DTOs"]
end

subgraph group_game["Quiz Gameplay"]
  node_service["Quiz Service<br/>[QuizService.java]"]
end

subgraph group_storage["Player and Question Data"]
  node_questiondata["Question Data<br/>[Question.java]"]
  node_playerdata["Player Data<br/>[Player.java]"]
  node_questionrepo["Question Repository"]
  node_playerrepo["Player Repository"]
  node_database[("Relational Database")]
end

node_players(("Players"))

node_players -->|"send messages"| node_controller
node_controller -->|"dispatches actions"| node_service
node_controller -->|"accepts payloads"| node_messages
node_service -->|"sends updates"| node_messages
node_service -->|"loads questions"| node_questionrepo
node_service -->|"reads and saves players"| node_playerrepo
node_questionrepo -->|"queries"| node_questiondata
node_playerrepo -->|"queries"| node_playerdata
node_questionrepo -.->|"persists via JPA"| node_database
node_playerrepo -.->|"persists via JPA"| node_database

click node_controller "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/controller/QuizController.java"
click node_messages "https://github.com/lllnightlll/math-jackbox/tree/main/src/main/java/com/quiz/backend/dto"
click node_service "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/service/QuizService.java"
click node_questiondata "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/model/Question.java"
click node_playerdata "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/model/Player.java"
click node_questionrepo "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/QuestionRepository.java"
click node_playerrepo "https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/PlayerRepository.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_messages toneBlue
class node_service toneAmber
class node_questiondata,node_playerdata,node_questionrepo,node_playerrepo,node_database toneMint
class node_players toneIndigo
```

## Components

### Realtime Interface

- [Quiz Controller](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/controller/QuizController.java): `src/main/java/com/quiz/backend/controller/QuizController.java`
- [Message DTOs](https://github.com/lllnightlll/math-jackbox/tree/main/src/main/java/com/quiz/backend/dto): `src/main/java/com/quiz/backend/dto`

### Quiz Gameplay

- [Quiz Service](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/service/QuizService.java): `src/main/java/com/quiz/backend/service/QuizService.java`

### Player and Question Data

- [Question Data](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/model/Question.java): `src/main/java/com/quiz/backend/model/Question.java`
- [Player Data](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/model/Player.java): `src/main/java/com/quiz/backend/model/Player.java`
- [Question Repository](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/QuestionRepository.java): `src/main/java/com/quiz/backend/repository/QuestionRepository.java`
- [Player Repository](https://github.com/lllnightlll/math-jackbox/blob/main/src/main/java/com/quiz/backend/repository/PlayerRepository.java): `src/main/java/com/quiz/backend/repository/PlayerRepository.java`
- **Relational Database**

### Other components

- **Players**

## Connections

- Players → Quiz Controller: send messages (evidence: `src/main/java/com/quiz/backend/controller/QuizController.java`)
- Quiz Controller → Quiz Service: dispatches actions (evidence: `src/main/java/com/quiz/backend/controller/QuizController.java`)
- Quiz Controller → Message DTOs: accepts payloads (evidence: `src/main/java/com/quiz/backend/controller/QuizController.java`)
- Quiz Service → Message DTOs: sends updates (evidence: `src/main/java/com/quiz/backend/service/QuizService.java`)
- Quiz Service → Question Repository: loads questions (evidence: `src/main/java/com/quiz/backend/service/QuizService.java`)
- Quiz Service → Player Repository: reads and saves players (evidence: `src/main/java/com/quiz/backend/service/QuizService.java`)
- Question Repository → Question Data: queries (evidence: `src/main/java/com/quiz/backend/repository/QuestionRepository.java`)
- Player Repository → Player Data: queries (evidence: `src/main/java/com/quiz/backend/repository/PlayerRepository.java`)
- Question Repository → Relational Database: persists via JPA
- Player Repository → Relational Database: persists via JPA
