# ahron-gutierrez/fluidia architecture

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

## Overview

Fluidia is a browser-based physics-learning application. Learners enter through the routed app, study fluid concepts in lessons and simulations, then practice through quizzes, sandboxes, and story-driven quests. Gameplay and account activity contribute to saved progress, achievements, and leaderboard views. The graph groups those user-facing domains and includes the shared account/progress layer. Relationships to unsampled feature internals are limited to routing or documented capabilities; the README describes the backend account API but not its implementation.

Main entry points: [`src/App.jsx`](https://github.com/ahron-gutierrez/fluidia/blob/main/src/App.jsx) (Route application), [`src/data/gameData.js`](https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/gameData.js) (Account progress), [`src/pages`](https://github.com/ahron-gutierrez/fluidia/tree/main/src/pages) (Quest experiences), [`src/features/quiz`](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/quiz) (Quiz hub and runs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Lessons and practice"]
  node_lessons["Fluid lessons"]
  node_overview["Lesson overview<br/>[Overview.jsx]"]
  node_lesson_sims["Lesson simulations<br/>[simulation.jsx]"]
  node_quiz_hub["Quiz hub and runs"]
  node_quiz_data["Quiz content<br/>[quizData.js]"]
  node_sandbox["Physics sandboxes"]
  node_chatbot["Learning chatbot"]
end

subgraph group_adventure["Story and quests"]
  node_story["Story introduction<br/>[StoryIntro.jsx]"]
  node_quests["Quest experiences"]
  node_platformer["Buoyancy game"]
  node_endless["Endless challenges"]
end

subgraph group_progress["Accounts and progress"]
  node_achievements["Achievement rules<br/>[achievements.js]"]
  node_game_data["Account progress<br/>[gameData.js]"]
  node_api_client["Account API client<br/>[api.js]"]
  node_leaderboard["Leaderboard<br/>[Leaderboard.jsx]"]
  node_account_pages["Account screens"]
end

subgraph group_shared["Shared experience"]
  node_map["World map<br/>[FluidiaMap.jsx]"]
  node_avatar["Avatar animation<br/>[AnimatedAvatar.jsx]"]
  node_effects["Game effects<br/>[pixelFx.js]"]
  node_sound["Sound effects<br/>[sfx.js]"]
end

node_learner(("Learner"))
node_app["Route application<br/>[App.jsx]"]
node_backend["Fluidia backend"]

node_learner -->|"opens"| node_app
node_app -->|"routes to"| node_lessons
node_app -->|"routes to"| node_overview
node_app -->|"routes to"| node_quiz_hub
node_app -->|"routes to"| node_sandbox
node_app -->|"mounts"| node_chatbot
node_app -->|"routes to"| node_story
node_app -->|"routes to"| node_quests
node_app -->|"routes to"| node_endless
node_app -->|"routes to"| node_leaderboard
node_app -->|"routes to"| node_account_pages
node_learner -.->|"explores"| node_lesson_sims
node_learner -.->|"practices"| node_quiz_hub
node_learner -.->|"experiments"| node_sandbox
node_lesson_sims -.->|"records progress"| node_game_data
node_quiz_hub -.->|"uses questions"| node_quiz_data
node_quiz_hub -.->|"records results"| node_achievements
node_quests -->|"uses game"| node_platformer
node_quests -.->|"records outcomes"| node_achievements
node_platformer -->|"emits particles"| node_effects
node_platformer -->|"plays effects"| node_sound
node_endless -.->|"records runs"| node_achievements
node_achievements -->|"reads and updates"| node_game_data
node_game_data -->|"sends requests"| node_api_client
node_api_client -->|"calls account API"| node_backend
node_leaderboard -.->|"reads account data"| node_game_data
node_account_pages -.->|"uses account state"| node_game_data
node_map -.->|"reads game state"| node_game_data
node_story -->|"reads player state"| node_game_data
node_story -->|"renders avatar"| node_avatar
node_quests -->|"renders avatar"| node_avatar

click node_app "https://github.com/ahron-gutierrez/fluidia/blob/main/src/App.jsx"
click node_lessons "https://github.com/ahron-gutierrez/fluidia/tree/main/src/features"
click node_overview "https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/Overview.jsx"
click node_lesson_sims "https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/04_archimedes/simulation.jsx"
click node_quiz_hub "https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/quiz"
click node_quiz_data "https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/quiz/quizData.js"
click node_sandbox "https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/sandbox"
click node_chatbot "https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/chatbot"
click node_story "https://github.com/ahron-gutierrez/fluidia/blob/main/src/pages/StoryIntro.jsx"
click node_quests "https://github.com/ahron-gutierrez/fluidia/tree/main/src/pages"
click node_platformer "https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/BuoyancyPlatformer.jsx"
click node_endless "https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/endless"
click node_achievements "https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/achievements.js"
click node_game_data "https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/gameData.js"
click node_api_client "https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/api.js"
click node_leaderboard "https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/leaderboard/Leaderboard.jsx"
click node_account_pages "https://github.com/ahron-gutierrez/fluidia/tree/main/src/pages"
click node_map "https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/FluidiaMap.jsx"
click node_avatar "https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/AnimatedAvatar.jsx"
click node_effects "https://github.com/ahron-gutierrez/fluidia/blob/main/src/utils/pixelFx.js"
click node_sound "https://github.com/ahron-gutierrez/fluidia/blob/main/src/utils/sfx.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_lessons,node_overview,node_lesson_sims,node_quiz_hub,node_quiz_data,node_sandbox,node_chatbot toneBlue
class node_story,node_quests,node_platformer,node_endless toneAmber
class node_achievements,node_game_data,node_api_client,node_leaderboard,node_account_pages,node_app toneMint
class node_map,node_avatar,node_effects,node_sound toneRose
class node_learner,node_backend toneIndigo
```

## Components

### Lessons and practice

- [Fluid lessons](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features): `src/features`
- [Lesson overview](https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/Overview.jsx): `src/features/Overview.jsx`
- [Lesson simulations](https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/04_archimedes/simulation.jsx): `src/features/04_archimedes/simulation.jsx`
- [Quiz hub and runs](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/quiz): `src/features/quiz`
- [Quiz content](https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/quiz/quizData.js): `src/features/quiz/quizData.js`
- [Physics sandboxes](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/sandbox): `src/features/sandbox`
- [Learning chatbot](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/chatbot): `src/features/chatbot`

### Story and quests

- [Story introduction](https://github.com/ahron-gutierrez/fluidia/blob/main/src/pages/StoryIntro.jsx): `src/pages/StoryIntro.jsx`
- [Quest experiences](https://github.com/ahron-gutierrez/fluidia/tree/main/src/pages): `src/pages`
- [Buoyancy game](https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/BuoyancyPlatformer.jsx): `src/components/BuoyancyPlatformer.jsx`
- [Endless challenges](https://github.com/ahron-gutierrez/fluidia/tree/main/src/features/endless): `src/features/endless`

### Accounts and progress

- [Achievement rules](https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/achievements.js): `src/data/achievements.js`
- [Account progress](https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/gameData.js): `src/data/gameData.js`
- [Account API client](https://github.com/ahron-gutierrez/fluidia/blob/main/src/data/api.js): `src/data/api.js`
- [Leaderboard](https://github.com/ahron-gutierrez/fluidia/blob/main/src/features/leaderboard/Leaderboard.jsx): `src/features/leaderboard/Leaderboard.jsx`
- [Account screens](https://github.com/ahron-gutierrez/fluidia/tree/main/src/pages): `src/pages`

### Shared experience

- [World map](https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/FluidiaMap.jsx): `src/components/FluidiaMap.jsx`
- [Avatar animation](https://github.com/ahron-gutierrez/fluidia/blob/main/src/components/AnimatedAvatar.jsx): `src/components/AnimatedAvatar.jsx`
- [Game effects](https://github.com/ahron-gutierrez/fluidia/blob/main/src/utils/pixelFx.js): `src/utils/pixelFx.js`
- [Sound effects](https://github.com/ahron-gutierrez/fluidia/blob/main/src/utils/sfx.js): `src/utils/sfx.js`

### Other components

- **Learner**
- [Route application](https://github.com/ahron-gutierrez/fluidia/blob/main/src/App.jsx): `src/App.jsx`
- **Fluidia backend**

## Connections

- Learner → Route application: opens (evidence: `src/App.jsx`)
- Route application → Fluid lessons: routes to (evidence: `src/App.jsx`)
- Route application → Lesson overview: routes to (evidence: `src/App.jsx`)
- Route application → Quiz hub and runs: routes to (evidence: `src/App.jsx`)
- Route application → Physics sandboxes: routes to (evidence: `src/App.jsx`)
- Route application → Learning chatbot: mounts (evidence: `src/App.jsx`)
- Route application → Story introduction: routes to (evidence: `src/App.jsx`)
- Route application → Quest experiences: routes to (evidence: `src/App.jsx`)
- Route application → Endless challenges: routes to (evidence: `src/App.jsx`)
- Route application → Leaderboard: routes to (evidence: `src/App.jsx`)
- Route application → Account screens: routes to (evidence: `src/App.jsx`)
- Learner → Lesson simulations: explores (evidence: `README.md`)
- Learner → Quiz hub and runs: practices (evidence: `README.md`)
- Learner → Physics sandboxes: experiments (evidence: `README.md`)
- Lesson simulations → Account progress: records progress
- Quiz hub and runs → Quiz content: uses questions
- Quiz hub and runs → Achievement rules: records results (evidence: `src/data/achievements.js`)
- Quest experiences → Buoyancy game: uses game (evidence: `src/pages/LaboratoryQuest.jsx`)
- Quest experiences → Achievement rules: records outcomes (evidence: `src/pages/PlumberHouse.jsx`)
- Buoyancy game → Game effects: emits particles (evidence: `src/components/BuoyancyPlatformer.jsx`)
- Buoyancy game → Sound effects: plays effects (evidence: `src/components/BuoyancyPlatformer.jsx`)
- Endless challenges → Achievement rules: records runs
- Achievement rules → Account progress: reads and updates (evidence: `src/data/achievements.js`)
- Account progress → Account API client: sends requests (evidence: `src/data/gameData.js`)
- Account API client → Fluidia backend: calls account API (evidence: `README.md`)
- Leaderboard → Account progress: reads account data (evidence: `src/features/leaderboard/Leaderboard.jsx`)
- Account screens → Account progress: uses account state (evidence: `src/pages/PlumberHouse.jsx`)
- World map → Account progress: reads game state (evidence: `src/components/FluidiaMap.jsx`)
- Story introduction → Account progress: reads player state (evidence: `src/pages/StoryIntro.jsx`)
- Story introduction → Avatar animation: renders avatar (evidence: `src/pages/StoryIntro.jsx`)
- Quest experiences → Avatar animation: renders avatar (evidence: `src/pages/PlumberHouse.jsx`)