# vungotuong/thianhiennguyen architecture

> Architecture diagram of the GitHub repository vungotuong/thianhiennguyen, 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/vungotuong/thianhiennguyen
- Repository: https://github.com/vungotuong/thianhiennguyen

## Overview

This is a browser-based, bilingual island-adventure game. The player starts or resumes a voyage, enters their name, visits islands, completes story and puzzle encounters, collects compass fragments, and progresses toward a final island and ending. A shared game store tracks progress and achievements and autosaves it. The tree also shows specialized 3D island scenes, a prediction challenge, and a waterfall experience. The README is only a Vite template; relationships for unsampled components are included only where the source index or excerpts support them.

Main entry points: [`src/components/layout/GameShell.jsx`](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/layout/GameShell.jsx) (Game shell), [`src/pages/IslandPage.jsx`](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/IslandPage.jsx) (Island encounter), [`src/hooks/useGame.js`](https://github.com/vungotuong/thianhiennguyen/blob/main/src/hooks/useGame.js) (Game selectors), [`src/pages/TitleScreen.jsx`](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/TitleScreen.jsx) (Title screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App flow"]
  node_shell["Game shell<br/>[GameShell.jsx]"]
  node_title["Title screen<br/>[TitleScreen.jsx]"]
  node_identity["Identity and greeting<br/>[NameEntryPage.jsx]"]
  node_verify["Identity check"]
  node_map["World map<br/>[WorldMapPage.jsx]"]
  node_islandpage["Island encounter<br/>[IslandPage.jsx]"]
  node_finalpage["Final island page"]
  node_ending["Ending page<br/>[EndingPage.jsx]"]
end

subgraph group_state["Progress systems"]
  node_store["Game state<br/>[gameStore.js]"]
  node_gamehooks["Game selectors<br/>[useGame.js]"]
  node_save["Save system<br/>[saveSystem.js]"]
  node_islandlogic["Island progression<br/>[islandLogic.js]"]
  node_achievements["Achievement checks"]
end

subgraph group_islands["Island experiences"]
  node_islanddata["Island content<br/>[islands.js]"]
  node_world3d["Island 3D scenes"]
  node_prediction["Prediction challenge<br/>[Island4Scene.jsx]"]
  node_predictionlogic["Prediction logic"]
  node_waterfall["Waterfall experience"]
end

subgraph group_encounters["Puzzles and rewards"]
  node_puzzle["Puzzle engine<br/>[PuzzleEngine.jsx]"]
  node_puzzletypes["Puzzle types"]
  node_dialog["Story dialogue<br/>[DialogBox.jsx]"]
  node_fragments["Fragment reveal"]
  node_catalog["Game content data"]
end

subgraph group_world["World presentation"]
  node_ui["Shared interface"]
  node_hud["Heads-up display<br/>[HUD.jsx]"]
  node_achievetoast["Achievement toast"]
end

node_player(("Player"))

node_player -->|"starts voyage"| node_shell
node_shell -->|"routes scene"| node_title
node_shell -->|"routes scene"| node_identity
node_shell -->|"routes scene"| node_verify
node_shell -->|"routes scene"| node_map
node_shell -->|"routes scene"| node_islandpage
node_shell -->|"routes scene"| node_finalpage
node_shell -->|"routes scene"| node_ending
node_title -->|"reads and updates"| node_gamehooks
node_title -->|"loads save"| node_save
node_shell -->|"selects scene"| node_gamehooks
node_gamehooks -->|"selects state"| node_store
node_gamehooks -->|"reads island data"| node_islanddata
node_store -->|"derives unlocks"| node_islandlogic
node_store -->|"checks unlocks"| node_achievements
node_store -->|"autosaves state"| node_save
node_islandpage -->|"reads progress"| node_gamehooks
node_islandpage -->|"selects island"| node_islanddata
node_islandpage -->|"renders dialogue"| node_dialog
node_islandpage -->|"renders puzzles"| node_puzzle
node_islandpage -->|"renders scenes"| node_world3d
node_islandpage -->|"reveals fragments"| node_fragments
node_puzzle -->|"dispatches type"| node_puzzletypes
node_puzzle -->|"reads registry"| node_catalog
node_world3d -.->|"includes challenge"| node_prediction
node_prediction -->|"gets predictions"| node_predictionlogic
node_prediction -->|"reads prediction data"| node_catalog
node_shell -->|"renders experience"| node_waterfall
node_shell -->|"renders HUD"| node_hud
node_shell -->|"renders toast"| node_achievetoast
node_achievetoast -.->|"reads toast queue"| node_gamehooks
node_fragments -->|"reads fragments"| node_gamehooks
node_puzzle -->|"uses panel"| node_ui
node_title -->|"uses controls"| node_ui

click node_shell "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/layout/GameShell.jsx"
click node_title "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/TitleScreen.jsx"
click node_identity "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/NameEntryPage.jsx"
click node_verify "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/VerifyIdentityPage.jsx"
click node_map "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/WorldMapPage.jsx"
click node_islandpage "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/IslandPage.jsx"
click node_finalpage "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/FinalIslandPage.jsx"
click node_ending "https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/EndingPage.jsx"
click node_store "https://github.com/vungotuong/thianhiennguyen/blob/main/src/store/gameStore.js"
click node_gamehooks "https://github.com/vungotuong/thianhiennguyen/blob/main/src/hooks/useGame.js"
click node_save "https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/saveSystem.js"
click node_islandlogic "https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/islandLogic.js"
click node_achievements "https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/achievementEngine.js"
click node_islanddata "https://github.com/vungotuong/thianhiennguyen/blob/main/src/data/islands.js"
click node_world3d "https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/world3d"
click node_prediction "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/world3d/island4/Island4Scene.jsx"
click node_predictionlogic "https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/predictionEngine.js"
click node_waterfall "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/waterfall/WaterfallExperience.jsx"
click node_puzzle "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/puzzle/PuzzleEngine.jsx"
click node_puzzletypes "https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/puzzle/types"
click node_dialog "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/dialog/DialogBox.jsx"
click node_fragments "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/inventory/FragmentRevealModal.jsx"
click node_catalog "https://github.com/vungotuong/thianhiennguyen/tree/main/src/data"
click node_ui "https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/ui"
click node_hud "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/layout/HUD.jsx"
click node_achievetoast "https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/achievements/AchievementToast.jsx"

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_shell,node_title,node_identity,node_verify,node_map,node_islandpage,node_finalpage,node_ending toneBlue
class node_store,node_gamehooks,node_save,node_islandlogic,node_achievements toneAmber
class node_islanddata,node_world3d,node_prediction,node_predictionlogic,node_waterfall toneMint
class node_puzzle,node_puzzletypes,node_dialog,node_fragments,node_catalog toneRose
class node_ui,node_hud,node_achievetoast,node_player toneIndigo
```

## Components

### App flow

- [Game shell](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/layout/GameShell.jsx): `src/components/layout/GameShell.jsx`
- [Title screen](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/TitleScreen.jsx): `src/pages/TitleScreen.jsx`
- [Identity and greeting](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/NameEntryPage.jsx): `src/pages/NameEntryPage.jsx`
- [Identity check](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/VerifyIdentityPage.jsx): `src/pages/VerifyIdentityPage.jsx`
- [World map](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/WorldMapPage.jsx): `src/pages/WorldMapPage.jsx`
- [Island encounter](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/IslandPage.jsx): `src/pages/IslandPage.jsx`
- [Final island page](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/FinalIslandPage.jsx): `src/pages/FinalIslandPage.jsx`
- [Ending page](https://github.com/vungotuong/thianhiennguyen/blob/main/src/pages/EndingPage.jsx): `src/pages/EndingPage.jsx`

### Progress systems

- [Game state](https://github.com/vungotuong/thianhiennguyen/blob/main/src/store/gameStore.js): `src/store/gameStore.js`
- [Game selectors](https://github.com/vungotuong/thianhiennguyen/blob/main/src/hooks/useGame.js): `src/hooks/useGame.js`
- [Save system](https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/saveSystem.js): `src/utils/saveSystem.js`
- [Island progression](https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/islandLogic.js): `src/utils/islandLogic.js`
- [Achievement checks](https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/achievementEngine.js): `src/utils/achievementEngine.js`

### Island experiences

- [Island content](https://github.com/vungotuong/thianhiennguyen/blob/main/src/data/islands.js): `src/data/islands.js`
- [Island 3D scenes](https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/world3d): `src/components/world3d`
- [Prediction challenge](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/world3d/island4/Island4Scene.jsx): `src/components/world3d/island4/Island4Scene.jsx`
- [Prediction logic](https://github.com/vungotuong/thianhiennguyen/blob/main/src/utils/predictionEngine.js): `src/utils/predictionEngine.js`
- [Waterfall experience](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/waterfall/WaterfallExperience.jsx): `src/components/waterfall/WaterfallExperience.jsx`

### Puzzles and rewards

- [Puzzle engine](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/puzzle/PuzzleEngine.jsx): `src/components/puzzle/PuzzleEngine.jsx`
- [Puzzle types](https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/puzzle/types): `src/components/puzzle/types`
- [Story dialogue](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/dialog/DialogBox.jsx): `src/components/dialog/DialogBox.jsx`
- [Fragment reveal](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/inventory/FragmentRevealModal.jsx): `src/components/inventory/FragmentRevealModal.jsx`
- [Game content data](https://github.com/vungotuong/thianhiennguyen/tree/main/src/data): `src/data`

### World presentation

- [Shared interface](https://github.com/vungotuong/thianhiennguyen/tree/main/src/components/ui): `src/components/ui`
- [Heads-up display](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/layout/HUD.jsx): `src/components/layout/HUD.jsx`
- [Achievement toast](https://github.com/vungotuong/thianhiennguyen/blob/main/src/components/achievements/AchievementToast.jsx): `src/components/achievements/AchievementToast.jsx`

### Other components

- **Player**

## Connections

- Player → Game shell: starts voyage (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Title screen: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Identity and greeting: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Identity check: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → World map: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Island encounter: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Final island page: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Ending page: routes scene (evidence: `src/components/layout/GameShell.jsx`)
- Title screen → Game selectors: reads and updates (evidence: `src/pages/TitleScreen.jsx`)
- Title screen → Save system: loads save (evidence: `src/pages/TitleScreen.jsx`)
- Game shell → Game selectors: selects scene (evidence: `src/components/layout/GameShell.jsx`)
- Game selectors → Game state: selects state (evidence: `src/hooks/useGame.js`)
- Game selectors → Island content: reads island data (evidence: `src/hooks/useGame.js`)
- Game state → Island progression: derives unlocks (evidence: `src/store/gameStore.js`)
- Game state → Achievement checks: checks unlocks (evidence: `src/store/gameStore.js`)
- Game state → Save system: autosaves state (evidence: `src/store/gameStore.js`)
- Island encounter → Game selectors: reads progress (evidence: `src/pages/IslandPage.jsx`)
- Island encounter → Island content: selects island
- Island encounter → Story dialogue: renders dialogue (evidence: `src/pages/IslandPage.jsx`)
- Island encounter → Puzzle engine: renders puzzles (evidence: `src/pages/IslandPage.jsx`)
- Island encounter → Island 3D scenes: renders scenes (evidence: `src/pages/IslandPage.jsx`)
- Island encounter → Fragment reveal: reveals fragments (evidence: `src/pages/IslandPage.jsx`)
- Puzzle engine → Puzzle types: dispatches type (evidence: `src/components/puzzle/PuzzleEngine.jsx`)
- Puzzle engine → Game content data: reads registry (evidence: `src/components/puzzle/PuzzleEngine.jsx`)
- Island 3D scenes → Prediction challenge: includes challenge (evidence: `src/components/world3d/island4/Island4Scene.jsx`)
- Prediction challenge → Prediction logic: gets predictions (evidence: `src/components/world3d/island4/Island4Scene.jsx`)
- Prediction challenge → Game content data: reads prediction data (evidence: `src/components/world3d/island4/Island4Scene.jsx`)
- Game shell → Waterfall experience: renders experience (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Heads-up display: renders HUD (evidence: `src/components/layout/GameShell.jsx`)
- Game shell → Achievement toast: renders toast (evidence: `src/components/layout/GameShell.jsx`)
- Achievement toast → Game selectors: reads toast queue
- Fragment reveal → Game selectors: reads fragments (evidence: `src/components/inventory/FragmentRevealModal.jsx`)
- Puzzle engine → Shared interface: uses panel (evidence: `src/components/puzzle/PuzzleEngine.jsx`)
- Title screen → Shared interface: uses controls (evidence: `src/pages/TitleScreen.jsx`)
