# chefnguyen/goiflow architecture

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

- Interactive diagram: https://gitdiagram.com/chefnguyen/goiflow
- Repository: https://github.com/chefnguyen/goiflow

## Overview

GoiFlow is a Japanese vocabulary-learning game with account/profile features, multiplayer rooms, live quiz rounds, Shiritori, history, leaderboards, and a vocabulary library. The main workflow is a player joining or creating a room, playing rounds, submitting answers, and viewing results. Source excerpts show parts of the game, auth, and vocabulary paths; other branches are represented from the repository tree, with unverified links marked dashed.

Main entry points: [`api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ActiveGamePlayService.java) (Live round engine), [`api/src/main/java/com/goiflow/repository`](https://github.com/chefnguyen/goiflow/tree/main/api/src/main/java/com/goiflow/repository) (Relational data), [`api/src/main/java/com/goiflow/service/GameSessionService.java`](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameSessionService.java) (Session lifecycle), [`api/src/main/java/com/goiflow/controller/GameSessionController.java`](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/GameSessionController.java) (Room and session API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webgame["Game screen<br/>[page.tsx]"]
  node_webshiritori["Shiritori screen<br/>[page.tsx]"]
  node_webhistory["History screen<br/>[page.tsx]"]
  node_webresults["Results screen<br/>[page.tsx]"]
  node_webleaderboard["Leaderboard screen"]
  node_weblibrary["Vocabulary library<br/>[library-client.tsx]"]
  node_webprofile["Profile screen<br/>[page.tsx]"]
  node_authui["Sign-up screen<br/>[page.tsx]"]
end

subgraph group_identity["Identity and profile"]
  node_authcontroller["Auth endpoints"]
  node_authservice["Auth service<br/>[AuthService.java]"]
  node_oauth["OAuth integration"]
  node_profileservice["Profile service"]
end

subgraph group_gameplay["Multiplayer gameplay"]
  node_rooms["Room and session API"]
  node_sessions["Session lifecycle"]
  node_liveplay["Live round engine"]
  node_shiritoriservice["Shiritori rules"]
  node_historyservice["Game history"]
  node_resultservice["Results and ranking"]
  node_leaderboardservice["Leaderboard service"]
  node_shiritoriapi["Shiritori endpoints"]
end

subgraph group_learning["Learning and discovery"]
  node_libraryservice["Library service"]
  node_contentselection["Content selection"]
  node_vocabularyapi["Vocabulary endpoints"]
end

subgraph group_persistence["Persistence and cache"]
  node_db[("Relational data")]
  node_vocabentity["Vocabulary entries"]
  node_sessionentity["Game session data"]
  node_participantentity["Participant data"]
  node_roundentity["Round data"]
  node_submissionentity["Answer submissions"]
  node_redis[("Redis cache")]
end

node_player(("Player"))
node_email["Email delivery<br/>[EmailService.java]"]

node_player -.->|"plays in"| node_webgame
node_webgame -.->|"calls"| node_rooms
node_rooms -->|"delegates to"| node_sessions
node_rooms -->|"delegates to"| node_liveplay
node_rooms -->|"delegates to"| node_historyservice
node_sessions -->|"resets play state"| node_liveplay
node_sessions -->|"reads and writes"| node_db
node_liveplay -->|"reads and writes"| node_db
node_liveplay -->|"formats vocabulary"| node_contentselection
node_liveplay -->|"caches entries"| node_redis
node_liveplay -->|"loads entries"| node_vocabentity
node_sessions -->|"persists sessions"| node_sessionentity
node_sessions -->|"persists players"| node_participantentity
node_liveplay -->|"persists rounds"| node_roundentity
node_liveplay -->|"records answers"| node_submissionentity
node_vocabularyapi -->|"delegates to"| node_contentselection
node_vocabularyapi -->|"uses cache"| node_redis
node_contentselection -.->|"selects vocabulary"| node_db
node_webshiritori -.->|"calls"| node_shiritoriapi
node_shiritoriapi -.->|"delegates to"| node_shiritoriservice
node_shiritoriservice -->|"reads and writes"| node_db
node_shiritoriservice -->|"uses cache"| node_redis
node_weblibrary -.->|"calls"| node_vocabularyapi
node_webhistory -.->|"calls"| node_historyservice
node_webresults -.->|"calls"| node_resultservice
node_webleaderboard -.->|"calls"| node_leaderboardservice
node_weblibrary -.->|"calls"| node_libraryservice
node_authui -.->|"submits credentials"| node_authcontroller
node_authcontroller -.->|"delegates to"| node_authservice
node_authservice -->|"stores accounts and OTPs"| node_db
node_authservice -->|"sends OTP"| node_email
node_authcontroller -.->|"supports sign-in"| node_oauth
node_webprofile -.->|"calls"| node_profileservice
node_libraryservice -.->|"reads library data"| node_db
node_historyservice -.->|"reads game history"| node_db
node_resultservice -.->|"reads results"| node_db
node_leaderboardservice -.->|"reads rankings"| node_db

click node_webgame "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/game/page.tsx"
click node_webshiritori "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/shiritori/page.tsx"
click node_webhistory "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/history/page.tsx"
click node_webresults "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/results/page.tsx"
click node_webleaderboard "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/leaderboard/leaderboard-client.tsx"
click node_weblibrary "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/library/library-client.tsx"
click node_webprofile "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/(protected)/profile/page.tsx"
click node_authui "https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(auth)/sign-up/page.tsx"
click node_authcontroller "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/AuthController.java"
click node_authservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/AuthService.java"
click node_oauth "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/security/CustomOAuth2UserService.java"
click node_profileservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ProfileService.java"
click node_rooms "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/GameSessionController.java"
click node_sessions "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameSessionService.java"
click node_liveplay "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ActiveGamePlayService.java"
click node_shiritoriservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ShiritoriService.java"
click node_historyservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameHistoryService.java"
click node_resultservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameResultsService.java"
click node_leaderboardservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/LeaderboardService.java"
click node_libraryservice "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/LibraryService.java"
click node_contentselection "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ContentSelectionService.java"
click node_vocabularyapi "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/VocabularyController.java"
click node_shiritoriapi "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/ShiritoriController.java"
click node_db "https://github.com/chefnguyen/goiflow/tree/main/api/src/main/java/com/goiflow/repository"
click node_vocabentity "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/content/VocabularyEntryEntity.java"
click node_sessionentity "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameSessionEntity.java"
click node_participantentity "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameParticipantEntity.java"
click node_roundentity "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameRoundEntity.java"
click node_submissionentity "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameSubmissionEntity.java"
click node_redis "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/RedisCacheService.java"
click node_email "https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/EmailService.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_webgame,node_webshiritori,node_webhistory,node_webresults,node_webleaderboard,node_weblibrary,node_webprofile,node_authui toneBlue
class node_authcontroller,node_authservice,node_oauth,node_profileservice toneAmber
class node_rooms,node_sessions,node_liveplay,node_shiritoriservice,node_historyservice,node_resultservice,node_leaderboardservice,node_shiritoriapi toneMint
class node_libraryservice,node_contentselection,node_vocabularyapi toneRose
class node_db,node_vocabentity,node_sessionentity,node_participantentity,node_roundentity,node_submissionentity,node_redis,node_player toneIndigo
class node_email toneTeal
```

## Components

### Web client

- [Game screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/game/page.tsx): `web/src/app/(app)/game/page.tsx`
- [Shiritori screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/shiritori/page.tsx): `web/src/app/(app)/shiritori/page.tsx`
- [History screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/history/page.tsx): `web/src/app/(app)/history/page.tsx`
- [Results screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/results/page.tsx): `web/src/app/(app)/results/page.tsx`
- [Leaderboard screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/leaderboard/leaderboard-client.tsx): `web/src/app/(app)/leaderboard/leaderboard-client.tsx`
- [Vocabulary library](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/library/library-client.tsx): `web/src/app/(app)/library/library-client.tsx`
- [Profile screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(app)/(protected)/profile/page.tsx): `web/src/app/(app)/(protected)/profile/page.tsx`
- [Sign-up screen](https://github.com/chefnguyen/goiflow/blob/main/web/src/app/(auth)/sign-up/page.tsx): `web/src/app/(auth)/sign-up/page.tsx`

### Identity and profile

- [Auth endpoints](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/AuthController.java): `api/src/main/java/com/goiflow/controller/AuthController.java`
- [Auth service](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/AuthService.java): `api/src/main/java/com/goiflow/service/AuthService.java`
- [OAuth integration](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/security/CustomOAuth2UserService.java): `api/src/main/java/com/goiflow/security/CustomOAuth2UserService.java`
- [Profile service](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ProfileService.java): `api/src/main/java/com/goiflow/service/ProfileService.java`

### Multiplayer gameplay

- [Room and session API](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/GameSessionController.java): `api/src/main/java/com/goiflow/controller/GameSessionController.java`
- [Session lifecycle](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameSessionService.java): `api/src/main/java/com/goiflow/service/GameSessionService.java`
- [Live round engine](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ActiveGamePlayService.java): `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`
- [Shiritori rules](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ShiritoriService.java): `api/src/main/java/com/goiflow/service/ShiritoriService.java`
- [Game history](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameHistoryService.java): `api/src/main/java/com/goiflow/service/GameHistoryService.java`
- [Results and ranking](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/GameResultsService.java): `api/src/main/java/com/goiflow/service/GameResultsService.java`
- [Leaderboard service](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/LeaderboardService.java): `api/src/main/java/com/goiflow/service/LeaderboardService.java`
- [Shiritori endpoints](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/ShiritoriController.java): `api/src/main/java/com/goiflow/controller/ShiritoriController.java`

### Learning and discovery

- [Library service](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/LibraryService.java): `api/src/main/java/com/goiflow/service/LibraryService.java`
- [Content selection](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/ContentSelectionService.java): `api/src/main/java/com/goiflow/service/ContentSelectionService.java`
- [Vocabulary endpoints](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/controller/VocabularyController.java): `api/src/main/java/com/goiflow/controller/VocabularyController.java`

### Persistence and cache

- [Relational data](https://github.com/chefnguyen/goiflow/tree/main/api/src/main/java/com/goiflow/repository): `api/src/main/java/com/goiflow/repository`
- [Vocabulary entries](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/content/VocabularyEntryEntity.java): `api/src/main/java/com/goiflow/entity/content/VocabularyEntryEntity.java`
- [Game session data](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameSessionEntity.java): `api/src/main/java/com/goiflow/entity/game/GameSessionEntity.java`
- [Participant data](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameParticipantEntity.java): `api/src/main/java/com/goiflow/entity/game/GameParticipantEntity.java`
- [Round data](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameRoundEntity.java): `api/src/main/java/com/goiflow/entity/game/GameRoundEntity.java`
- [Answer submissions](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/entity/game/GameSubmissionEntity.java): `api/src/main/java/com/goiflow/entity/game/GameSubmissionEntity.java`
- [Redis cache](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/RedisCacheService.java): `api/src/main/java/com/goiflow/service/RedisCacheService.java`

### Other components

- **Player**
- [Email delivery](https://github.com/chefnguyen/goiflow/blob/main/api/src/main/java/com/goiflow/service/EmailService.java): `api/src/main/java/com/goiflow/service/EmailService.java`

## Connections

- Player → Game screen: plays in
- Game screen → Room and session API: calls
- Room and session API → Session lifecycle: delegates to (evidence: `api/src/main/java/com/goiflow/controller/GameSessionController.java`)
- Room and session API → Live round engine: delegates to (evidence: `api/src/main/java/com/goiflow/controller/GameSessionController.java`)
- Room and session API → Game history: delegates to (evidence: `api/src/main/java/com/goiflow/controller/GameSessionController.java`)
- Session lifecycle → Live round engine: resets play state (evidence: `api/src/main/java/com/goiflow/service/GameSessionService.java`)
- Session lifecycle → Relational data: reads and writes (evidence: `api/src/main/java/com/goiflow/service/GameSessionService.java`)
- Live round engine → Relational data: reads and writes (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Live round engine → Content selection: formats vocabulary (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Live round engine → Redis cache: caches entries (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Live round engine → Vocabulary entries: loads entries (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Session lifecycle → Game session data: persists sessions (evidence: `api/src/main/java/com/goiflow/service/GameSessionService.java`)
- Session lifecycle → Participant data: persists players (evidence: `api/src/main/java/com/goiflow/service/GameSessionService.java`)
- Live round engine → Round data: persists rounds (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Live round engine → Answer submissions: records answers (evidence: `api/src/main/java/com/goiflow/service/ActiveGamePlayService.java`)
- Vocabulary endpoints → Content selection: delegates to (evidence: `api/src/main/java/com/goiflow/controller/VocabularyController.java`)
- Vocabulary endpoints → Redis cache: uses cache (evidence: `api/src/main/java/com/goiflow/controller/VocabularyController.java`)
- Content selection → Relational data: selects vocabulary
- Shiritori screen → Shiritori endpoints: calls
- Shiritori endpoints → Shiritori rules: delegates to
- Shiritori rules → Relational data: reads and writes (evidence: `api/src/main/java/com/goiflow/service/ShiritoriService.java`)
- Shiritori rules → Redis cache: uses cache (evidence: `api/src/main/java/com/goiflow/service/ShiritoriService.java`)
- Vocabulary library → Vocabulary endpoints: calls
- History screen → Game history: calls
- Results screen → Results and ranking: calls
- Leaderboard screen → Leaderboard service: calls
- Vocabulary library → Library service: calls
- Sign-up screen → Auth endpoints: submits credentials
- Auth endpoints → Auth service: delegates to (evidence: `api/src/main/java/com/goiflow/controller/AuthController.java`)
- Auth service → Relational data: stores accounts and OTPs (evidence: `api/src/main/java/com/goiflow/service/AuthService.java`)
- Auth service → Email delivery: sends OTP (evidence: `api/src/main/java/com/goiflow/service/AuthService.java`)
- Auth endpoints → OAuth integration: supports sign-in
- Profile screen → Profile service: calls
- Library service → Relational data: reads library data
- Game history → Relational data: reads game history
- Results and ranking → Relational data: reads results
- Leaderboard service → Relational data: reads rankings
