# sinator12/studyquest architecture

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

- Interactive diagram: https://gitdiagram.com/sinator12/studyquest
- Repository: https://github.com/sinator12/studyquest

## Overview

StudyQuest is a browser-based study and learning app. Users enter through the routed React app, authenticate or continue as a guest, then study with decks, AI-assisted question generation, explanations and plans, games, focus sessions, and progress tracking. Local stores partition study data by account, with Supabase authentication and cloud progress restoration. The character lab is a separate interactive preview workflow. Edges reflect the supplied imports and excerpts; unsampled capabilities are represented where their paths are known, but their internal wiring is not inferred.

Main entry points: [`src/App.tsx`](https://github.com/sinator12/studyquest/blob/main/src/App.tsx) (Route application), [`src/site/studyStore.ts`](https://github.com/sinator12/studyquest/blob/main/src/site/studyStore.ts) (Deck and stats store), [`src/site/TopNav.tsx`](https://github.com/sinator12/studyquest/blob/main/src/site/TopNav.tsx) (Study navigation), [`src/site/progressSync.ts`](https://github.com/sinator12/studyquest/blob/main/src/site/progressSync.ts) (Cloud progress sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App routing"]
  node_app["Route application<br/>[App.tsx]"]
  node_authgate["Auth gate<br/>[AuthGate.tsx]"]
end

subgraph group_learning["Study experience"]
  node_dashboard["Study dashboard<br/>[DashboardPage.tsx]"]
  node_plan["Study planner<br/>[StudyPlanPage.tsx]"]
  node_explain["Answer explanations<br/>[ExplainPage.tsx]"]
  node_ai["AI question service<br/>[aiService.ts]"]
  node_quiz["Quiz content<br/>[quizData.ts]"]
  node_nav["Study navigation<br/>[TopNav.tsx]"]
end

subgraph group_state["Identity and progress"]
  node_study[("Deck and stats store<br/>[studyStore.ts]")]
  node_auth[("Account store<br/>[authStore.ts]")]
  node_supabase["Supabase auth client<br/>[supabaseClient.ts]"]
  node_sync["Cloud progress sync<br/>[progressSync.ts]"]
  node_focus[("Focus sessions<br/>[focusStore.ts]")]
end

subgraph group_games["Learning games"]
  node_gamespage["Games catalog<br/>[GamesPage.tsx]"]
  node_gameplay["Quiz gameplay<br/>[GamePlayPage.tsx]"]
  node_cafe["Study Cafe<br/>[StudyCafeGame.tsx]"]
  node_angry["Angry Nerds<br/>[AngryNerdsGame.tsx]"]
  node_bingo["Bingo Night<br/>[BingoNightGame.tsx]"]
  node_gamesdata["Game definitions<br/>[gamesData.ts]"]
end

subgraph group_character["Character lab"]
  node_characterlab["Character preview<br/>[CharacterLab.tsx]"]
  node_controller["State transitions<br/>[stateController.ts]"]
  node_stage["Character stage<br/>[CharacterStage.tsx]"]
  node_sprite["Character renderer"]
  node_artwork["Pose artwork<br/>[artwork.ts]"]
end

node_learner(("Learner"))

node_learner -->|"opens"| node_app
node_app -->|"wraps routes"| node_authgate
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_plan
node_app -->|"routes to"| node_explain
node_app -->|"routes to"| node_gamespage
node_app -->|"routes to"| node_gameplay
node_app -->|"routes to"| node_cafe
node_app -->|"routes to"| node_angry
node_app -->|"routes to"| node_bingo
node_app -->|"routes to"| node_characterlab
node_app -->|"initializes auth"| node_supabase
node_app -->|"restores progress"| node_sync
node_authgate -->|"reads identity"| node_auth
node_authgate -->|"uses auth"| node_supabase
node_supabase -->|"updates profile"| node_auth
node_sync -->|"uses client"| node_supabase
node_sync -->|"reads identity"| node_auth
node_sync -->|"syncs study data"| node_study
node_sync -->|"syncs sessions"| node_focus
node_dashboard -->|"requests generation"| node_ai
node_plan -->|"requests generation"| node_ai
node_explain -->|"requests assistance"| node_ai
node_ai -->|"reads AI config"| node_study
node_ai -->|"uses question type"| node_quiz
node_dashboard -->|"reads study state"| node_study
node_plan -->|"reads study state"| node_study
node_explain -->|"reads study state"| node_study
node_gamespage -->|"reads catalog"| node_gamesdata
node_gameplay -->|"reads game data"| node_gamesdata
node_gamespage -->|"reads progress"| node_study
node_gameplay -->|"updates study state"| node_study
node_cafe -->|"updates study state"| node_study
node_angry -->|"updates study state"| node_study
node_bingo -->|"updates study state"| node_study
node_cafe -->|"uses questions"| node_quiz
node_angry -->|"uses questions"| node_quiz
node_bingo -->|"uses questions"| node_quiz
node_gameplay -->|"uses questions"| node_quiz
node_nav -->|"reads deck and stats"| node_study
node_nav -->|"reads account"| node_auth
node_nav -->|"signs out"| node_supabase
node_nav -->|"records sessions"| node_focus
node_dashboard -->|"renders"| node_nav
node_plan -->|"renders"| node_nav
node_explain -->|"renders"| node_nav
node_gamespage -->|"renders"| node_nav
node_gameplay -->|"renders"| node_nav

click node_app "https://github.com/sinator12/studyquest/blob/main/src/App.tsx"
click node_authgate "https://github.com/sinator12/studyquest/blob/main/src/site/AuthGate.tsx"
click node_dashboard "https://github.com/sinator12/studyquest/blob/main/src/site/DashboardPage.tsx"
click node_plan "https://github.com/sinator12/studyquest/blob/main/src/site/StudyPlanPage.tsx"
click node_explain "https://github.com/sinator12/studyquest/blob/main/src/site/ExplainPage.tsx"
click node_ai "https://github.com/sinator12/studyquest/blob/main/src/site/aiService.ts"
click node_quiz "https://github.com/sinator12/studyquest/blob/main/src/site/quizData.ts"
click node_study "https://github.com/sinator12/studyquest/blob/main/src/site/studyStore.ts"
click node_auth "https://github.com/sinator12/studyquest/blob/main/src/site/authStore.ts"
click node_supabase "https://github.com/sinator12/studyquest/blob/main/src/site/supabaseClient.ts"
click node_sync "https://github.com/sinator12/studyquest/blob/main/src/site/progressSync.ts"
click node_focus "https://github.com/sinator12/studyquest/blob/main/src/site/focusStore.ts"
click node_nav "https://github.com/sinator12/studyquest/blob/main/src/site/TopNav.tsx"
click node_gamespage "https://github.com/sinator12/studyquest/blob/main/src/site/GamesPage.tsx"
click node_gameplay "https://github.com/sinator12/studyquest/blob/main/src/site/GamePlayPage.tsx"
click node_cafe "https://github.com/sinator12/studyquest/blob/main/src/site/StudyCafeGame.tsx"
click node_angry "https://github.com/sinator12/studyquest/blob/main/src/site/AngryNerdsGame.tsx"
click node_bingo "https://github.com/sinator12/studyquest/blob/main/src/site/BingoNightGame.tsx"
click node_gamesdata "https://github.com/sinator12/studyquest/blob/main/src/site/gamesData.ts"
click node_characterlab "https://github.com/sinator12/studyquest/blob/main/src/character/CharacterLab.tsx"
click node_controller "https://github.com/sinator12/studyquest/blob/main/src/character/stateController.ts"
click node_stage "https://github.com/sinator12/studyquest/blob/main/src/character/CharacterStage.tsx"
click node_sprite "https://github.com/sinator12/studyquest/blob/main/src/character/StudyQuestCharacter.tsx"
click node_artwork "https://github.com/sinator12/studyquest/blob/main/src/character/artwork.ts"

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_authgate toneBlue
class node_dashboard,node_plan,node_explain,node_ai,node_quiz,node_nav toneAmber
class node_study,node_auth,node_supabase,node_sync,node_focus toneMint
class node_gamespage,node_gameplay,node_cafe,node_angry,node_bingo,node_gamesdata toneRose
class node_characterlab,node_controller,node_stage,node_sprite,node_artwork,node_learner toneIndigo
```

## Components

### App routing

- [Route application](https://github.com/sinator12/studyquest/blob/main/src/App.tsx): `src/App.tsx`
- [Auth gate](https://github.com/sinator12/studyquest/blob/main/src/site/AuthGate.tsx): `src/site/AuthGate.tsx`

### Study experience

- [Study dashboard](https://github.com/sinator12/studyquest/blob/main/src/site/DashboardPage.tsx): `src/site/DashboardPage.tsx`
- [Study planner](https://github.com/sinator12/studyquest/blob/main/src/site/StudyPlanPage.tsx): `src/site/StudyPlanPage.tsx`
- [Answer explanations](https://github.com/sinator12/studyquest/blob/main/src/site/ExplainPage.tsx): `src/site/ExplainPage.tsx`
- [AI question service](https://github.com/sinator12/studyquest/blob/main/src/site/aiService.ts): `src/site/aiService.ts`
- [Quiz content](https://github.com/sinator12/studyquest/blob/main/src/site/quizData.ts): `src/site/quizData.ts`
- [Study navigation](https://github.com/sinator12/studyquest/blob/main/src/site/TopNav.tsx): `src/site/TopNav.tsx`

### Identity and progress

- [Deck and stats store](https://github.com/sinator12/studyquest/blob/main/src/site/studyStore.ts): `src/site/studyStore.ts`
- [Account store](https://github.com/sinator12/studyquest/blob/main/src/site/authStore.ts): `src/site/authStore.ts`
- [Supabase auth client](https://github.com/sinator12/studyquest/blob/main/src/site/supabaseClient.ts): `src/site/supabaseClient.ts`
- [Cloud progress sync](https://github.com/sinator12/studyquest/blob/main/src/site/progressSync.ts): `src/site/progressSync.ts`
- [Focus sessions](https://github.com/sinator12/studyquest/blob/main/src/site/focusStore.ts): `src/site/focusStore.ts`

### Learning games

- [Games catalog](https://github.com/sinator12/studyquest/blob/main/src/site/GamesPage.tsx): `src/site/GamesPage.tsx`
- [Quiz gameplay](https://github.com/sinator12/studyquest/blob/main/src/site/GamePlayPage.tsx): `src/site/GamePlayPage.tsx`
- [Study Cafe](https://github.com/sinator12/studyquest/blob/main/src/site/StudyCafeGame.tsx): `src/site/StudyCafeGame.tsx`
- [Angry Nerds](https://github.com/sinator12/studyquest/blob/main/src/site/AngryNerdsGame.tsx): `src/site/AngryNerdsGame.tsx`
- [Bingo Night](https://github.com/sinator12/studyquest/blob/main/src/site/BingoNightGame.tsx): `src/site/BingoNightGame.tsx`
- [Game definitions](https://github.com/sinator12/studyquest/blob/main/src/site/gamesData.ts): `src/site/gamesData.ts`

### Character lab

- [Character preview](https://github.com/sinator12/studyquest/blob/main/src/character/CharacterLab.tsx): `src/character/CharacterLab.tsx`
- [State transitions](https://github.com/sinator12/studyquest/blob/main/src/character/stateController.ts): `src/character/stateController.ts`
- [Character stage](https://github.com/sinator12/studyquest/blob/main/src/character/CharacterStage.tsx): `src/character/CharacterStage.tsx`
- [Character renderer](https://github.com/sinator12/studyquest/blob/main/src/character/StudyQuestCharacter.tsx): `src/character/StudyQuestCharacter.tsx`
- [Pose artwork](https://github.com/sinator12/studyquest/blob/main/src/character/artwork.ts): `src/character/artwork.ts`

### Other components

- **Learner**

## Connections

- Learner → Route application: opens (evidence: `src/App.tsx`)
- Route application → Auth gate: wraps routes (evidence: `src/App.tsx`)
- Route application → Study dashboard: routes to (evidence: `src/App.tsx`)
- Route application → Study planner: routes to (evidence: `src/App.tsx`)
- Route application → Answer explanations: routes to (evidence: `src/App.tsx`)
- Route application → Games catalog: routes to (evidence: `src/App.tsx`)
- Route application → Quiz gameplay: routes to (evidence: `src/App.tsx`)
- Route application → Study Cafe: routes to (evidence: `src/App.tsx`)
- Route application → Angry Nerds: routes to (evidence: `src/App.tsx`)
- Route application → Bingo Night: routes to (evidence: `src/App.tsx`)
- Route application → Character preview: routes to (evidence: `src/App.tsx`)
- Route application → Supabase auth client: initializes auth (evidence: `src/App.tsx`)
- Route application → Cloud progress sync: restores progress (evidence: `src/App.tsx`)
- Auth gate → Account store: reads identity (evidence: `src/site/AuthGate.tsx`)
- Auth gate → Supabase auth client: uses auth (evidence: `src/site/AuthGate.tsx`)
- Supabase auth client → Account store: updates profile (evidence: `src/site/supabaseClient.ts`)
- Cloud progress sync → Supabase auth client: uses client (evidence: `src/site/progressSync.ts`)
- Cloud progress sync → Account store: reads identity (evidence: `src/site/progressSync.ts`)
- Cloud progress sync → Deck and stats store: syncs study data (evidence: `src/site/progressSync.ts`)
- Cloud progress sync → Focus sessions: syncs sessions (evidence: `src/site/progressSync.ts`)
- Study dashboard → AI question service: requests generation (evidence: `src/site/DashboardPage.tsx`)
- Study planner → AI question service: requests generation (evidence: `src/site/StudyPlanPage.tsx`)
- Answer explanations → AI question service: requests assistance (evidence: `src/site/ExplainPage.tsx`)
- AI question service → Deck and stats store: reads AI config (evidence: `src/site/aiService.ts`)
- AI question service → Quiz content: uses question type (evidence: `src/site/aiService.ts`)
- Study dashboard → Deck and stats store: reads study state (evidence: `src/site/DashboardPage.tsx`)
- Study planner → Deck and stats store: reads study state (evidence: `src/site/StudyPlanPage.tsx`)
- Answer explanations → Deck and stats store: reads study state (evidence: `src/site/ExplainPage.tsx`)
- Games catalog → Game definitions: reads catalog (evidence: `src/site/GamesPage.tsx`)
- Quiz gameplay → Game definitions: reads game data (evidence: `src/site/GamePlayPage.tsx`)
- Games catalog → Deck and stats store: reads progress (evidence: `src/site/GamesPage.tsx`)
- Quiz gameplay → Deck and stats store: updates study state (evidence: `src/site/GamePlayPage.tsx`)
- Study Cafe → Deck and stats store: updates study state (evidence: `src/site/StudyCafeGame.tsx`)
- Angry Nerds → Deck and stats store: updates study state (evidence: `src/site/AngryNerdsGame.tsx`)
- Bingo Night → Deck and stats store: updates study state (evidence: `src/site/BingoNightGame.tsx`)
- Study Cafe → Quiz content: uses questions (evidence: `src/site/StudyCafeGame.tsx`)
- Angry Nerds → Quiz content: uses questions (evidence: `src/site/AngryNerdsGame.tsx`)
- Bingo Night → Quiz content: uses questions (evidence: `src/site/BingoNightGame.tsx`)
- Quiz gameplay → Quiz content: uses questions (evidence: `src/site/GamePlayPage.tsx`)
- Study navigation → Deck and stats store: reads deck and stats (evidence: `src/site/TopNav.tsx`)
- Study navigation → Account store: reads account (evidence: `src/site/TopNav.tsx`)
- Study navigation → Supabase auth client: signs out (evidence: `src/site/TopNav.tsx`)
- Study navigation → Focus sessions: records sessions (evidence: `src/site/TopNav.tsx`)
- Study dashboard → Study navigation: renders (evidence: `src/site/DashboardPage.tsx`)
- Study planner → Study navigation: renders (evidence: `src/site/StudyPlanPage.tsx`)
- Answer explanations → Study navigation: renders (evidence: `src/site/ExplainPage.tsx`)
- Games catalog → Study navigation: renders (evidence: `src/site/GamesPage.tsx`)
- Quiz gameplay → Study navigation: renders (evidence: `src/site/GamePlayPage.tsx`)
