# ahron-gutierrez/frontend architecture

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

- Interactive diagram: https://gitdiagram.com/ahron-gutierrez/frontend
- Repository: https://github.com/ahron-gutierrez/frontend

## Overview

Fluidia is a browser-based fluid-science learning game. Learners enter through the app, explore lessons and story quests, then practice with quizzes, sandboxes, or endless runs; account progress, achievements, and leaderboard features support that learning loop. The graph also preserves the chatbot and avatar/customization capabilities. Routing and several imports are visible in excerpts or the source index; unsampled feature internals are represented at their known entry files, without inferred internal call chains.

Main entry points: [`src/App.jsx`](https://github.com/ahron-gutierrez/frontend/blob/main/src/App.jsx) (App router), [`src/pages/LaboratoryQuest.jsx`](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/LaboratoryQuest.jsx) (Laboratory quest), [`src/features`](https://github.com/ahron-gutierrez/frontend/tree/main/src/features) (Fluid lessons), [`src/pages/StoryIntro.jsx`](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/StoryIntro.jsx) (Story introduction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and accounts"]
  node_app["App router<br/>[App.jsx]"]
  node_account["Accounts<br/>[gameData.js]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_learning["Science learning"]
  node_lessons["Fluid lessons"]
  node_lesson_nav["Lesson navigation"]
  node_quiz["Quiz hub and runs"]
  node_quiz_data["Quiz content<br/>[quizData.js]"]
  node_sandbox["Science sandboxes"]
end

subgraph group_gameplay["Story gameplay"]
  node_story["Story introduction<br/>[StoryIntro.jsx]"]
  node_map["World map<br/>[FluidiaMap.jsx]"]
  node_hydro_quest["Hydrostatic quest"]
  node_plumber["Plumber quest<br/>[PlumberHouse.jsx]"]
  node_lab_quest["Laboratory quest"]
  node_platformer["Buoyancy game"]
  node_endless["Endless challenges"]
  node_generators["Challenge generators<br/>[generators.js]"]
end

subgraph group_progress["Progress and community"]
  node_progress_data[("Game state<br/>[gameData.js]")]
  node_achievements["Achievements<br/>[achievements.js]"]
  node_achievement_page["Achievement page<br/>[Achievements.jsx]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
  node_avatar_editor["Avatar editing<br/>[AvatarEditor.jsx]"]
  node_chatbot["Chat assistant<br/>[ChatBot.jsx]"]
  node_chat_client["Chat client<br/>[chatClient.js]"]
end

subgraph group_shared["Shared runtime"]
  node_avatar_assets["Avatar assets<br/>[avatarAssets.js]"]
  node_avatar["Animated avatar<br/>[AnimatedAvatar.jsx]"]
  node_music["Background music<br/>[BgMusic.jsx]"]
  node_leave["Leave confirmation<br/>[ConfirmLeave.jsx]"]
  node_hints["Learning hints<br/>[HintHelper.jsx]"]
  node_summary["Quest summary<br/>[QuestSummary.jsx]"]
  node_round_intro["Round intro<br/>[RoundIntro.jsx]"]
  node_pixel_water["Water rendering<br/>[PixelWater.jsx]"]
  node_sprite_slot["Sprite display<br/>[SpriteSlot.jsx]"]
  node_pixel_fx["Pixel effects<br/>[pixelFx.js]"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_app
node_app -->|"routes to"| node_story
node_app -->|"routes to"| node_hydro_quest
node_app -->|"routes to"| node_plumber
node_app -->|"routes to"| node_lab_quest
node_app -->|"routes to"| node_lessons
node_app -->|"routes to"| node_quiz
node_app -->|"routes to"| node_sandbox
node_app -->|"routes to"| node_endless
node_app -->|"routes to"| node_leaderboard
node_app -->|"routes to"| node_achievement_page
node_app -->|"renders"| node_chatbot
node_lessons -->|"uses"| node_lesson_nav
node_lessons -->|"reads"| node_progress_data
node_lessons -->|"uses"| node_music
node_quiz -->|"reads"| node_quiz_data
node_lab_quest -->|"renders"| node_platformer
node_lab_quest -->|"renders"| node_leave
node_lab_quest -->|"renders"| node_hints
node_lab_quest -->|"renders"| node_summary
node_plumber -->|"renders"| node_hints
node_plumber -->|"renders"| node_summary
node_plumber -->|"reads avatar"| node_progress_data
node_platformer -->|"renders"| node_pixel_water
node_platformer -->|"renders"| node_sprite_slot
node_platformer -->|"emits effects"| node_pixel_fx
node_story -->|"reads progress"| node_progress_data
node_story -->|"renders"| node_avatar
node_story -->|"renders"| node_sprite_slot
node_endless -.->|"uses"| node_generators
node_achievements -->|"reads and writes"| node_progress_data
node_achievement_page -.->|"uses"| node_achievements
node_leaderboard -->|"requests data"| node_api
node_leaderboard -->|"renders"| node_avatar
node_account -->|"sends requests"| node_api
node_chatbot -.->|"uses"| node_chat_client
node_chat_client -->|"uses"| node_api
node_learner -.->|"authenticates"| node_api
node_chat_client -.->|"streams replies"| node_learner
node_avatar -->|"loads sprites"| node_avatar_assets

click node_app "https://github.com/ahron-gutierrez/frontend/blob/main/src/App.jsx"
click node_account "https://github.com/ahron-gutierrez/frontend/blob/main/src/data/gameData.js"
click node_api "https://github.com/ahron-gutierrez/frontend/blob/main/src/data/api.js"
click node_lessons "https://github.com/ahron-gutierrez/frontend/tree/main/src/features"
click node_lesson_nav "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/LessonBottomNavigation.jsx"
click node_quiz "https://github.com/ahron-gutierrez/frontend/tree/main/src/features/quiz"
click node_quiz_data "https://github.com/ahron-gutierrez/frontend/blob/main/src/features/quiz/quizData.js"
click node_sandbox "https://github.com/ahron-gutierrez/frontend/tree/main/src/features/sandbox"
click node_story "https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/StoryIntro.jsx"
click node_map "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/FluidiaMap.jsx"
click node_hydro_quest "https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/QuestHydrostatic.jsx"
click node_plumber "https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/PlumberHouse.jsx"
click node_lab_quest "https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/LaboratoryQuest.jsx"
click node_platformer "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/BuoyancyPlatformer.jsx"
click node_endless "https://github.com/ahron-gutierrez/frontend/tree/main/src/features/endless"
click node_generators "https://github.com/ahron-gutierrez/frontend/blob/main/src/features/endless/generators.js"
click node_progress_data "https://github.com/ahron-gutierrez/frontend/blob/main/src/data/gameData.js"
click node_achievements "https://github.com/ahron-gutierrez/frontend/blob/main/src/data/achievements.js"
click node_achievement_page "https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/Achievements.jsx"
click node_leaderboard "https://github.com/ahron-gutierrez/frontend/blob/main/src/features/leaderboard/Leaderboard.jsx"
click node_avatar_editor "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/AvatarEditor.jsx"
click node_chatbot "https://github.com/ahron-gutierrez/frontend/blob/main/src/features/chatbot/ChatBot.jsx"
click node_chat_client "https://github.com/ahron-gutierrez/frontend/blob/main/src/features/chatbot/chatClient.js"
click node_avatar_assets "https://github.com/ahron-gutierrez/frontend/blob/main/src/data/avatarAssets.js"
click node_avatar "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/AnimatedAvatar.jsx"
click node_music "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/BgMusic.jsx"
click node_leave "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/ConfirmLeave.jsx"
click node_hints "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/HintHelper.jsx"
click node_summary "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/QuestSummary.jsx"
click node_round_intro "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/RoundIntro.jsx"
click node_pixel_water "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/PixelWater.jsx"
click node_sprite_slot "https://github.com/ahron-gutierrez/frontend/blob/main/src/components/SpriteSlot.jsx"
click node_pixel_fx "https://github.com/ahron-gutierrez/frontend/blob/main/src/utils/pixelFx.js"

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_account,node_api toneBlue
class node_lessons,node_lesson_nav,node_quiz,node_quiz_data,node_sandbox toneAmber
class node_story,node_map,node_hydro_quest,node_plumber,node_lab_quest,node_platformer,node_endless,node_generators toneMint
class node_progress_data,node_achievements,node_achievement_page,node_leaderboard,node_avatar_editor,node_chatbot,node_chat_client toneRose
class node_avatar_assets,node_avatar,node_music,node_leave,node_hints,node_summary,node_round_intro,node_pixel_water,node_sprite_slot,node_pixel_fx,node_learner toneIndigo
```

## Components

### App and accounts

- [App router](https://github.com/ahron-gutierrez/frontend/blob/main/src/App.jsx): `src/App.jsx`
- [Accounts](https://github.com/ahron-gutierrez/frontend/blob/main/src/data/gameData.js): `src/data/gameData.js`
- [API client](https://github.com/ahron-gutierrez/frontend/blob/main/src/data/api.js): `src/data/api.js`

### Science learning

- [Fluid lessons](https://github.com/ahron-gutierrez/frontend/tree/main/src/features): `src/features`
- [Lesson navigation](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/LessonBottomNavigation.jsx): `src/components/LessonBottomNavigation.jsx`
- [Quiz hub and runs](https://github.com/ahron-gutierrez/frontend/tree/main/src/features/quiz): `src/features/quiz`
- [Quiz content](https://github.com/ahron-gutierrez/frontend/blob/main/src/features/quiz/quizData.js): `src/features/quiz/quizData.js`
- [Science sandboxes](https://github.com/ahron-gutierrez/frontend/tree/main/src/features/sandbox): `src/features/sandbox`

### Story gameplay

- [Story introduction](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/StoryIntro.jsx): `src/pages/StoryIntro.jsx`
- [World map](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/FluidiaMap.jsx): `src/components/FluidiaMap.jsx`
- [Hydrostatic quest](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/QuestHydrostatic.jsx): `src/pages/QuestHydrostatic.jsx`
- [Plumber quest](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/PlumberHouse.jsx): `src/pages/PlumberHouse.jsx`
- [Laboratory quest](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/LaboratoryQuest.jsx): `src/pages/LaboratoryQuest.jsx`
- [Buoyancy game](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/BuoyancyPlatformer.jsx): `src/components/BuoyancyPlatformer.jsx`
- [Endless challenges](https://github.com/ahron-gutierrez/frontend/tree/main/src/features/endless): `src/features/endless`
- [Challenge generators](https://github.com/ahron-gutierrez/frontend/blob/main/src/features/endless/generators.js): `src/features/endless/generators.js`

### Progress and community

- [Game state](https://github.com/ahron-gutierrez/frontend/blob/main/src/data/gameData.js): `src/data/gameData.js`
- [Achievements](https://github.com/ahron-gutierrez/frontend/blob/main/src/data/achievements.js): `src/data/achievements.js`
- [Achievement page](https://github.com/ahron-gutierrez/frontend/blob/main/src/pages/Achievements.jsx): `src/pages/Achievements.jsx`
- [Leaderboard](https://github.com/ahron-gutierrez/frontend/blob/main/src/features/leaderboard/Leaderboard.jsx): `src/features/leaderboard/Leaderboard.jsx`
- [Avatar editing](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/AvatarEditor.jsx): `src/components/AvatarEditor.jsx`
- [Chat assistant](https://github.com/ahron-gutierrez/frontend/blob/main/src/features/chatbot/ChatBot.jsx): `src/features/chatbot/ChatBot.jsx`
- [Chat client](https://github.com/ahron-gutierrez/frontend/blob/main/src/features/chatbot/chatClient.js): `src/features/chatbot/chatClient.js`

### Shared runtime

- [Avatar assets](https://github.com/ahron-gutierrez/frontend/blob/main/src/data/avatarAssets.js): `src/data/avatarAssets.js`
- [Animated avatar](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/AnimatedAvatar.jsx): `src/components/AnimatedAvatar.jsx`
- [Background music](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/BgMusic.jsx): `src/components/BgMusic.jsx`
- [Leave confirmation](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/ConfirmLeave.jsx): `src/components/ConfirmLeave.jsx`
- [Learning hints](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/HintHelper.jsx): `src/components/HintHelper.jsx`
- [Quest summary](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/QuestSummary.jsx): `src/components/QuestSummary.jsx`
- [Round intro](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/RoundIntro.jsx): `src/components/RoundIntro.jsx`
- [Water rendering](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/PixelWater.jsx): `src/components/PixelWater.jsx`
- [Sprite display](https://github.com/ahron-gutierrez/frontend/blob/main/src/components/SpriteSlot.jsx): `src/components/SpriteSlot.jsx`
- [Pixel effects](https://github.com/ahron-gutierrez/frontend/blob/main/src/utils/pixelFx.js): `src/utils/pixelFx.js`

### Other components

- **Learner**

## Connections

- Learner → App router: opens (evidence: `src/App.jsx`)
- App router → Story introduction: routes to (evidence: `src/App.jsx`)
- App router → Hydrostatic quest: routes to (evidence: `src/App.jsx`)
- App router → Plumber quest: routes to (evidence: `src/App.jsx`)
- App router → Laboratory quest: routes to (evidence: `src/App.jsx`)
- App router → Fluid lessons: routes to (evidence: `src/App.jsx`)
- App router → Quiz hub and runs: routes to (evidence: `src/App.jsx`)
- App router → Science sandboxes: routes to (evidence: `src/App.jsx`)
- App router → Endless challenges: routes to (evidence: `src/App.jsx`)
- App router → Leaderboard: routes to (evidence: `src/App.jsx`)
- App router → Achievement page: routes to (evidence: `src/App.jsx`)
- App router → Chat assistant: renders (evidence: `src/App.jsx`)
- Fluid lessons → Lesson navigation: uses (evidence: `src/features/02_density/page.jsx`)
- Fluid lessons → Game state: reads (evidence: `src/features/02_density/page.jsx`)
- Fluid lessons → Background music: uses (evidence: `src/features/04_archimedes/simulation.jsx`)
- Quiz hub and runs → Quiz content: reads (evidence: `src/data/achievements.js`)
- Laboratory quest → Buoyancy game: renders (evidence: `src/pages/LaboratoryQuest.jsx`)
- Laboratory quest → Leave confirmation: renders (evidence: `src/pages/LaboratoryQuest.jsx`)
- Laboratory quest → Learning hints: renders (evidence: `src/pages/LaboratoryQuest.jsx`)
- Laboratory quest → Quest summary: renders (evidence: `src/pages/LaboratoryQuest.jsx`)
- Plumber quest → Learning hints: renders (evidence: `src/pages/PlumberHouse.jsx`)
- Plumber quest → Quest summary: renders (evidence: `src/pages/PlumberHouse.jsx`)
- Plumber quest → Game state: reads avatar (evidence: `src/pages/PlumberHouse.jsx`)
- Buoyancy game → Water rendering: renders (evidence: `src/components/BuoyancyPlatformer.jsx`)
- Buoyancy game → Sprite display: renders (evidence: `src/components/BuoyancyPlatformer.jsx`)
- Buoyancy game → Pixel effects: emits effects (evidence: `src/components/BuoyancyPlatformer.jsx`)
- Story introduction → Game state: reads progress (evidence: `src/pages/StoryIntro.jsx`)
- Story introduction → Animated avatar: renders (evidence: `src/pages/StoryIntro.jsx`)
- Story introduction → Sprite display: renders (evidence: `src/pages/StoryIntro.jsx`)
- Endless challenges → Challenge generators: uses
- Achievements → Game state: reads and writes (evidence: `src/data/achievements.js`)
- Achievement page → Achievements: uses
- Leaderboard → API client: requests data (evidence: `src/features/leaderboard/Leaderboard.jsx`)
- Leaderboard → Animated avatar: renders (evidence: `src/features/leaderboard/Leaderboard.jsx`)
- Accounts → API client: sends requests (evidence: `src/data/gameData.js`)
- Chat assistant → Chat client: uses
- Chat client → API client: uses (evidence: `src/features/chatbot/chatClient.js`)
- Learner → API client: authenticates (evidence: `README.md`)
- Chat client → Learner: streams replies (evidence: `README.md`)
- Animated avatar → Avatar assets: loads sprites (evidence: `src/components/AnimatedAvatar.jsx`)