# relay28/wordmaster architecture

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

- Interactive diagram: https://gitdiagram.com/relay28/wordmaster
- Repository: https://github.com/relay28/wordmaster

## Overview

WordMaster is a role-based language-learning platform. Teachers manage classrooms and learning content; students join configurable, role-based game sessions, practice through chat, and receive progress and assessment feedback. The graph highlights those user-facing stages, authentication, AI-assisted features, and persistent state. Some backend components are represented at subsystem level because their source was not sampled; links between them are shown only where the excerpts, SOURCE INDEX, or README support them.

Main entry points: [`frontend/wordmaster/src/AppRoutes.jsx`](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/AppRoutes.jsx) (Application routes), [`backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java`](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java) (Turn and game manager), [`backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java`](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java) (Authentication API), [`frontend/wordmaster/src/components/content/UploadContent.jsx`](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/content/UploadContent.jsx) (Content authoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and identity"]
  node_routes["Application routes<br/>[AppRoutes.jsx]"]
  node_authui["User auth state"]
  node_authcontroller["Authentication API"]
  node_authservice["Authentication service<br/>[AuthService.java]"]
end

subgraph group_learning["Classroom and content"]
  node_classroomui["Classroom management"]
  node_contentui["Content authoring<br/>[UploadContent.jsx]"]
  node_classroomapi["Classroom and content APIs"]
  node_ai["AI services<br/>[AIService.java]"]
end

subgraph group_game["Gameplay and assessment"]
  node_waiting["Waiting room"]
  node_gameui["Live gameplay<br/>[GameCore.jsx]"]
  node_sessionapi["Session orchestration"]
  node_manager["Turn and game manager"]
  node_chat["Gameplay chat<br/>[ChatService.java]"]
  node_assessment["Progress and assessment"]
  node_reports["Student reports"]
end

subgraph group_platform["Backend and persistence"]
  node_websocket["Real-time channel"]
  node_gector["Grammar checking service<br/>[gector_service.py]"]
  node_database[("MySQL database")]
  node_playerrepo["Player-session repository"]
end

node_user(("Teacher or student"))
node_microsoft{{"Microsoft identity"}}

node_user -->|"uses"| node_routes
node_routes -->|"checks identity"| node_authui
node_routes -->|"routes to"| node_classroomui
node_routes -->|"routes to"| node_waiting
node_routes -->|"routes to"| node_gameui
node_user -->|"authenticates"| node_authcontroller
node_authcontroller -->|"delegates to"| node_authservice
node_authservice -.->|"persists users"| node_database
node_authcontroller -->|"supports OAuth2"| node_microsoft
node_user -->|"manages classes"| node_classroomui
node_user -->|"creates content"| node_contentui
node_classroomui -.->|"uses API"| node_classroomapi
node_contentui -.->|"uses API"| node_classroomapi
node_contentui -->|"AI-assisted generation"| node_ai
node_user -->|"joins session"| node_waiting
node_waiting -.->|"starts session"| node_sessionapi
node_gameui -->|"real-time play"| node_websocket
node_sessionapi -.->|"delegates turns"| node_manager
node_manager -->|"reads and writes"| node_playerrepo
node_manager -.->|"requests prompts"| node_ai
node_manager -->|"updates progress"| node_assessment
node_gameui -.->|"submits messages"| node_chat
node_chat -.->|"broadcasts messages"| node_websocket
node_chat -.->|"grammar analysis"| node_gector
node_user -->|"reviews results"| node_reports
node_reports -.->|"views progress"| node_assessment
node_playerrepo -->|"queries"| node_database

click node_routes "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/AppRoutes.jsx"
click node_authui "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/context/UserAuthContext.jsx"
click node_authcontroller "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java"
click node_authservice "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AuthService.java"
click node_classroomui "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/Classroom/Classroom%20Details%20Page.jsx"
click node_contentui "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/content/UploadContent.jsx"
click node_classroomapi "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/ClassroomController.java"
click node_ai "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AIService.java"
click node_waiting "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/WaitingRoom/WaitingRoomPage.jsx"
click node_gameui "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/gameplay/GameCore.jsx"
click node_sessionapi "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionService.java"
click node_manager "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java"
click node_chat "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/ChatService.java"
click node_assessment "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/ProgressTrackingService.java"
click node_reports "https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/Reports/StudentReportPage.jsx"
click node_websocket "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/config/WebSocketConfig.java"
click node_gector "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/python-services/gector_service.py"
click node_playerrepo "https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/repository/PlayerSessionEntityRepository.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_routes,node_authui,node_authcontroller,node_authservice toneBlue
class node_classroomui,node_contentui,node_classroomapi,node_ai toneAmber
class node_waiting,node_gameui,node_sessionapi,node_manager,node_chat,node_assessment,node_reports toneMint
class node_websocket,node_gector,node_database,node_playerrepo toneRose
class node_user,node_microsoft toneIndigo
```

## Components

### Access and identity

- [Application routes](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/AppRoutes.jsx): `frontend/wordmaster/src/AppRoutes.jsx`
- [User auth state](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/context/UserAuthContext.jsx): `frontend/wordmaster/src/components/context/UserAuthContext.jsx`
- [Authentication API](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java`
- [Authentication service](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AuthService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AuthService.java`

### Classroom and content

- [Classroom management](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/Classroom/Classroom%20Details%20Page.jsx): `frontend/wordmaster/src/components/Classroom/Classroom Details Page.jsx`
- [Content authoring](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/content/UploadContent.jsx): `frontend/wordmaster/src/components/content/UploadContent.jsx`
- [Classroom and content APIs](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/ClassroomController.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/ClassroomController.java`
- [AI services](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AIService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/AIService.java`

### Gameplay and assessment

- [Waiting room](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/WaitingRoom/WaitingRoomPage.jsx): `frontend/wordmaster/src/components/WaitingRoom/WaitingRoomPage.jsx`
- [Live gameplay](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/gameplay/GameCore.jsx): `frontend/wordmaster/src/components/gameplay/GameCore.jsx`
- [Session orchestration](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionService.java`
- [Turn and game manager](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java`
- [Gameplay chat](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/ChatService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/ChatService.java`
- [Progress and assessment](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/ProgressTrackingService.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/ProgressTrackingService.java`
- [Student reports](https://github.com/relay28/wordmaster/blob/main/frontend/wordmaster/src/components/Reports/StudentReportPage.jsx): `frontend/wordmaster/src/components/Reports/StudentReportPage.jsx`

### Backend and persistence

- [Real-time channel](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/config/WebSocketConfig.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/config/WebSocketConfig.java`
- [Grammar checking service](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/python-services/gector_service.py): `backend/wrdmstr/python-services/gector_service.py`
- **MySQL database**
- [Player-session repository](https://github.com/relay28/wordmaster/blob/main/backend/wrdmstr/src/main/java/cit/edu/wrdmstr/repository/PlayerSessionEntityRepository.java): `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/repository/PlayerSessionEntityRepository.java`

### Other components

- **Teacher or student**
- **Microsoft identity**

## Connections

- Teacher or student → Application routes: uses (evidence: `frontend/wordmaster/src/AppRoutes.jsx`)
- Application routes → User auth state: checks identity (evidence: `frontend/wordmaster/src/AppRoutes.jsx`)
- Application routes → Classroom management: routes to (evidence: `frontend/wordmaster/src/AppRoutes.jsx`)
- Application routes → Waiting room: routes to (evidence: `frontend/wordmaster/src/AppRoutes.jsx`)
- Application routes → Live gameplay: routes to (evidence: `frontend/wordmaster/src/AppRoutes.jsx`)
- Teacher or student → Authentication API: authenticates (evidence: `README.md`)
- Authentication API → Authentication service: delegates to (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/controller/AuthController.java`)
- Authentication service → MySQL database: persists users
- Authentication API → Microsoft identity: supports OAuth2 (evidence: `README.md`)
- Teacher or student → Classroom management: manages classes (evidence: `README.md`)
- Teacher or student → Content authoring: creates content (evidence: `README.md`)
- Classroom management → Classroom and content APIs: uses API
- Content authoring → Classroom and content APIs: uses API
- Content authoring → AI services: AI-assisted generation (evidence: `README.md`)
- Teacher or student → Waiting room: joins session (evidence: `README.md`)
- Waiting room → Session orchestration: starts session
- Live gameplay → Real-time channel: real-time play (evidence: `README.md`)
- Session orchestration → Turn and game manager: delegates turns (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionService.java`)
- Turn and game manager → Player-session repository: reads and writes (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java`)
- Turn and game manager → AI services: requests prompts (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java`)
- Turn and game manager → Progress and assessment: updates progress (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/service/gameplay/GameSessionManagerService.java`)
- Live gameplay → Gameplay chat: submits messages
- Gameplay chat → Real-time channel: broadcasts messages
- Gameplay chat → Grammar checking service: grammar analysis
- Teacher or student → Student reports: reviews results (evidence: `README.md`)
- Student reports → Progress and assessment: views progress
- Player-session repository → MySQL database: queries (evidence: `backend/wrdmstr/src/main/java/cit/edu/wrdmstr/repository/PlayerSessionEntityRepository.java`)
