# tokushi12/capstone-wizardfrac architecture

> Architecture diagram of the GitHub repository tokushi12/capstone-wizardfrac, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tokushi12/capstone-wizardfrac
- Repository: https://github.com/tokushi12/capstone-wizardfrac

## Overview

WizardFrac is a React game-based fraction assessment experience backed by a Spring service. Students log in, choose a character and island/stage, play fraction mechanics, then have gameplay and progress recorded for dashboard and leaderboard reporting. The README documents similar-fraction Same Container, dissimilar-fraction Butterfly Method, mixed-fraction handling, three themed islands and step-level diagnostics. Backend call evidence is strongest for lobby setup and progress persistence; unsampled routes and frontend API details are omitted or shown only where documented.

Main entry points: [`backend/src/main/java/com/WizardFrac/WizardFrac/controller`](https://github.com/tokushi12/capstone-wizardfrac/tree/main/backend/src/main/java/com/WizardFrac/WizardFrac/controller) (REST controllers), [`frontend/src/App.jsx`](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/App.jsx) (App routing), [`frontend/src/pages/DissimilarIslandGame.jsx`](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/DissimilarIslandGame.jsx) (Dissimilar island), [`frontend/src/pages/HybridIslandGame.jsx`](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/HybridIslandGame.jsx) (Hybrid island)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_student["Student access"]
  node_app["App routing<br/>[App.jsx]"]
  node_login["Login<br/>[login.jsx]"]
  node_character["Character selection"]
  node_settings["Settings<br/>[SettingsPage.jsx]"]
end

subgraph group_game["Fraction gameplay"]
  node_lobby["Game lobby<br/>[game-lobby.jsx]"]
  node_similar["Similar island"]
  node_dissimilar["Dissimilar island"]
  node_hybrid["Hybrid island"]
  node_mixed["Mixed conversion"]
  node_drawing["Drawing input<br/>[DrawingCanvas.jsx]"]
  node_tutorials["Fraction tutorials"]
  node_audio["Audio controls<br/>[audio.js]"]
end

subgraph group_progress["Progress and reporting"]
  node_studentdash["Student dashboard"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
end

subgraph group_backend["Backend services"]
  node_api["REST controllers"]
  node_studentsvc["Student service"]
  node_charactersvc["Character service"]
  node_lobbysvc["Lobby service"]
  node_progresssvc["Progress service"]
  node_studentrepo[("Student records")]
  node_sessionrepo[("Game sessions")]
  node_progressrepo[("Progress records")]
  node_session["Session model<br/>[GameSession.java]"]
  node_progressmodel["Progress model<br/>[GameProgress.java]"]
end

node_player(("Student"))
node_database[("Relational database")]

node_player -->|"opens"| node_app
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_character
node_app -->|"routes to"| node_lobby
node_login -.->|"authenticates"| node_api
node_character -.->|"selects character"| node_api
node_lobby -.->|"starts session"| node_api
node_lobby -.->|"launches"| node_similar
node_lobby -.->|"launches"| node_dissimilar
node_lobby -.->|"launches"| node_hybrid
node_similar -->|"uses input"| node_drawing
node_dissimilar -->|"uses input"| node_drawing
node_hybrid -->|"uses input"| node_drawing
node_similar -->|"handles conversion"| node_mixed
node_dissimilar -->|"handles conversion"| node_mixed
node_hybrid -->|"handles conversion"| node_mixed
node_dissimilar -->|"renders"| node_tutorials
node_hybrid -.->|"teaches mechanic"| node_tutorials
node_similar -->|"plays effects"| node_audio
node_dissimilar -->|"plays effects"| node_audio
node_hybrid -->|"plays effects"| node_audio
node_app -->|"routes to"| node_studentdash
node_app -.->|"routes to"| node_leaderboard
node_app -.->|"routes to"| node_settings
node_api -->|"delegates"| node_studentsvc
node_api -->|"delegates"| node_charactersvc
node_api -->|"delegates"| node_lobbysvc
node_api -->|"delegates"| node_progresssvc
node_studentsvc -->|"reads/writes"| node_studentrepo
node_charactersvc -->|"loads student"| node_studentrepo
node_lobbysvc -->|"loads student"| node_studentrepo
node_lobbysvc -->|"loads progress"| node_progressrepo
node_lobbysvc -->|"saves session"| node_sessionrepo
node_progresssvc -->|"loads sessions"| node_sessionrepo
node_progresssvc -->|"updates progress"| node_progressrepo
node_sessionrepo -->|"stores"| node_session
node_progressrepo -->|"stores"| node_progressmodel
node_studentrepo -.->|"persists"| node_database
node_sessionrepo -.->|"persists"| node_database
node_progressrepo -.->|"persists"| node_database
node_similar -.->|"submits gameplay"| node_api
node_dissimilar -.->|"submits gameplay"| node_api
node_hybrid -.->|"submits gameplay"| node_api
node_studentdash -.->|"requests reports"| node_api
node_leaderboard -.->|"requests rankings"| node_api

click node_app "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/App.jsx"
click node_login "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/login.jsx"
click node_character "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/character-selection.jsx"
click node_lobby "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/game-lobby.jsx"
click node_similar "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/SimilarIslandGame.jsx"
click node_dissimilar "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/DissimilarIslandGame.jsx"
click node_hybrid "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/HybridIslandGame.jsx"
click node_mixed "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/ImproperToMixedGame.jsx"
click node_drawing "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/DrawingCanvas.jsx"
click node_tutorials "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/ButterflyTutorial.jsx"
click node_studentdash "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/StudentDashboard.jsx"
click node_leaderboard "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/Leaderboard.jsx"
click node_settings "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/SettingsPage.jsx"
click node_audio "https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/utils/audio.js"
click node_api "https://github.com/tokushi12/capstone-wizardfrac/tree/main/backend/src/main/java/com/WizardFrac/WizardFrac/controller"
click node_studentsvc "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/StudentService.java"
click node_charactersvc "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/CharacterService.java"
click node_lobbysvc "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java"
click node_progresssvc "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/GameProgressService.java"
click node_studentrepo "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/StudentRepository.java"
click node_sessionrepo "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameSessionRepository.java"
click node_progressrepo "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameProgressRepository.java"
click node_session "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameSession.java"
click node_progressmodel "https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameProgress.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_app,node_login,node_character,node_settings toneBlue
class node_lobby,node_similar,node_dissimilar,node_hybrid,node_mixed,node_drawing,node_tutorials,node_audio,node_database toneAmber
class node_studentdash,node_leaderboard toneMint
class node_api,node_studentsvc,node_charactersvc,node_lobbysvc,node_progresssvc,node_studentrepo,node_sessionrepo,node_progressrepo,node_session,node_progressmodel toneRose
class node_player toneIndigo
```

## Components

### Student access

- [App routing](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Login](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/login.jsx): `frontend/src/pages/login.jsx`
- [Character selection](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/character-selection.jsx): `frontend/src/pages/character-selection.jsx`
- [Settings](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/SettingsPage.jsx): `frontend/src/pages/SettingsPage.jsx`

### Fraction gameplay

- [Game lobby](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/game-lobby.jsx): `frontend/src/pages/game-lobby.jsx`
- [Similar island](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/SimilarIslandGame.jsx): `frontend/src/pages/SimilarIslandGame.jsx`
- [Dissimilar island](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/DissimilarIslandGame.jsx): `frontend/src/pages/DissimilarIslandGame.jsx`
- [Hybrid island](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/HybridIslandGame.jsx): `frontend/src/pages/HybridIslandGame.jsx`
- [Mixed conversion](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/ImproperToMixedGame.jsx): `frontend/src/components/ImproperToMixedGame.jsx`
- [Drawing input](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/DrawingCanvas.jsx): `frontend/src/components/DrawingCanvas.jsx`
- [Fraction tutorials](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/components/ButterflyTutorial.jsx): `frontend/src/components/ButterflyTutorial.jsx`
- [Audio controls](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/utils/audio.js): `frontend/src/utils/audio.js`

### Progress and reporting

- [Student dashboard](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/StudentDashboard.jsx): `frontend/src/pages/StudentDashboard.jsx`
- [Leaderboard](https://github.com/tokushi12/capstone-wizardfrac/blob/main/frontend/src/pages/Leaderboard.jsx): `frontend/src/pages/Leaderboard.jsx`

### Backend services

- [REST controllers](https://github.com/tokushi12/capstone-wizardfrac/tree/main/backend/src/main/java/com/WizardFrac/WizardFrac/controller): `backend/src/main/java/com/WizardFrac/WizardFrac/controller`
- [Student service](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/StudentService.java): `backend/src/main/java/com/WizardFrac/WizardFrac/service/StudentService.java`
- [Character service](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/CharacterService.java): `backend/src/main/java/com/WizardFrac/WizardFrac/service/CharacterService.java`
- [Lobby service](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java): `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java`
- [Progress service](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/service/GameProgressService.java): `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameProgressService.java`
- [Student records](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/StudentRepository.java): `backend/src/main/java/com/WizardFrac/WizardFrac/repository/StudentRepository.java`
- [Game sessions](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameSessionRepository.java): `backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameSessionRepository.java`
- [Progress records](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameProgressRepository.java): `backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameProgressRepository.java`
- [Session model](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameSession.java): `backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameSession.java`
- [Progress model](https://github.com/tokushi12/capstone-wizardfrac/blob/main/backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameProgress.java): `backend/src/main/java/com/WizardFrac/WizardFrac/entity/GameProgress.java`

### Other components

- **Student**
- **Relational database**

## Connections

- Student → App routing: opens (evidence: `frontend/src/App.jsx`)
- App routing → Login: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Character selection: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Game lobby: routes to (evidence: `frontend/src/App.jsx`)
- Login → REST controllers: authenticates
- Character selection → REST controllers: selects character
- Game lobby → REST controllers: starts session
- Game lobby → Similar island: launches
- Game lobby → Dissimilar island: launches
- Game lobby → Hybrid island: launches
- Similar island → Drawing input: uses input (evidence: `frontend/src/pages/SimilarIslandGame.jsx`)
- Dissimilar island → Drawing input: uses input (evidence: `frontend/src/pages/DissimilarIslandGame.jsx`)
- Hybrid island → Drawing input: uses input (evidence: `frontend/src/pages/HybridIslandGame.jsx`)
- Similar island → Mixed conversion: handles conversion (evidence: `frontend/src/pages/SimilarIslandGame.jsx`)
- Dissimilar island → Mixed conversion: handles conversion (evidence: `frontend/src/pages/DissimilarIslandGame.jsx`)
- Hybrid island → Mixed conversion: handles conversion (evidence: `frontend/src/pages/HybridIslandGame.jsx`)
- Dissimilar island → Fraction tutorials: renders (evidence: `frontend/src/pages/DissimilarIslandGame.jsx`)
- Hybrid island → Fraction tutorials: teaches mechanic
- Similar island → Audio controls: plays effects (evidence: `frontend/src/pages/SimilarIslandGame.jsx`)
- Dissimilar island → Audio controls: plays effects (evidence: `frontend/src/pages/DissimilarIslandGame.jsx`)
- Hybrid island → Audio controls: plays effects (evidence: `frontend/src/pages/HybridIslandGame.jsx`)
- App routing → Student dashboard: routes to (evidence: `frontend/src/App.jsx`)
- App routing → Leaderboard: routes to
- App routing → Settings: routes to
- REST controllers → Student service: delegates (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/controller/StudentController.java`)
- REST controllers → Character service: delegates (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/controller/CharacterController.java`)
- REST controllers → Lobby service: delegates (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/controller/GameLobbyController.java`)
- REST controllers → Progress service: delegates (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/controller/GameProgressController.java`)
- Student service → Student records: reads/writes (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/StudentService.java`)
- Character service → Student records: loads student (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/CharacterService.java`)
- Lobby service → Student records: loads student (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java`)
- Lobby service → Progress records: loads progress (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java`)
- Lobby service → Game sessions: saves session (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameLobbyService.java`)
- Progress service → Game sessions: loads sessions (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameProgressService.java`)
- Progress service → Progress records: updates progress (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/service/GameProgressService.java`)
- Game sessions → Session model: stores (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameSessionRepository.java`)
- Progress records → Progress model: stores (evidence: `backend/src/main/java/com/WizardFrac/WizardFrac/repository/GameProgressRepository.java`)
- Student records → Relational database: persists
- Game sessions → Relational database: persists
- Progress records → Relational database: persists
- Similar island → REST controllers: submits gameplay
- Dissimilar island → REST controllers: submits gameplay
- Hybrid island → REST controllers: submits gameplay
- Student dashboard → REST controllers: requests reports
- Leaderboard → REST controllers: requests rankings