# knnagesh78/neuroquest architecture

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

- Interactive diagram: https://gitdiagram.com/knnagesh78/neuroquest
- Repository: https://github.com/knnagesh78/neuroquest

## Overview

NeuroQuest is a private, account-backed 3D memory-palace study app. The main journey is sign-in and workspace loading, creating or selecting a palace, adding spatial memory anchors, then exploring notes or practicing recall and saving review progress. Its README also highlights search, learning insights, export, and install/offline support. Edges reflect cited imports and calls or explicit README behavior; several unsampled modules are represented by their exact directories, so internal links for those capabilities are omitted where wiring is not evidenced.

Main entry points: [`src/components/account/AccountGate.tsx`](https://github.com/knnagesh78/neuroquest/blob/main/src/components/account/AccountGate.tsx) (Account gate), [`src/components/NeuroQuest.tsx`](https://github.com/knnagesh78/neuroquest/blob/main/src/components/NeuroQuest.tsx) (Workspace shell), [`src/store/usePalaceStore.ts`](https://github.com/knnagesh78/neuroquest/blob/main/src/store/usePalaceStore.ts) (Palace state), [`src/components/three/Scene.tsx`](https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/Scene.tsx) (Scene renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_account["Account &amp; sync"]
  node_auth["Account gate<br/>[AccountGate.tsx]"]
  node_firebase["Firebase services<br/>[firebase.ts]"]
  node_accountlib["Account helpers<br/>[account.ts]"]
  node_sync["Workspace sync<br/>[workspace-cloud.ts]"]
  node_savequeue["Save queue<br/>[save-queue.ts]"]
  node_accountcontrols["Account controls"]
  node_accountstate["Account status<br/>[useAccountStore.ts]"]
end

subgraph group_workspace["Palace workspace"]
  node_workspaceui["Workspace shell<br/>[NeuroQuest.tsx]"]
  node_palacestore["Palace state<br/>[usePalaceStore.ts]"]
  node_sampledata["Starter palaces<br/>[data.ts]"]
  node_navigation["Palace navigation<br/>[Navigation.tsx]"]
  node_roomform["Create palace<br/>[AddRoomModal.tsx]"]
end

subgraph group_study["Study experience"]
  node_anchorform["Create anchor<br/>[AddAnchorModal.tsx]"]
  node_drawer["Study drawer<br/>[AnchorDrawer.tsx]"]
  node_mode["Study mode<br/>[ModeSwitcher.tsx]"]
  node_searchinsights["Search &amp; insights<br/>[NeuroQuest.tsx]"]
end

subgraph group_scene["3D environment"]
  node_scene["Scene renderer<br/>[Scene.tsx]"]
  node_memoryanchor["Spatial artifacts<br/>[MemoryAnchor.tsx]"]
  node_camera["Camera controls"]
end

subgraph group_platform["Install &amp; offline"]
  node_install["Install wizard<br/>[InstallWizard.tsx]"]
  node_offline["Offline worker<br/>[sw.js]"]
end

node_learner(("Learner"))
node_firebaseauth["Firebase Auth"]
node_firestore[("Cloud Firestore")]
node_browser(("Browser"))

node_learner -->|"signs in"| node_auth
node_auth -->|"initializes"| node_firebase
node_auth -->|"formats errors"| node_accountlib
node_auth -->|"authenticates"| node_firebaseauth
node_auth -->|"loads workspace"| node_sync
node_auth -->|"queues saves"| node_savequeue
node_auth -->|"replaces state"| node_palacestore
node_auth -->|"mounts workspace"| node_workspaceui
node_auth -->|"renders sync controls"| node_accountcontrols
node_auth -.->|"updates status"| node_accountstate
node_sync -.->|"reads and writes"| node_firestore
node_savequeue -.->|"batches saves"| node_sync
node_learner -->|"uses workspace"| node_workspaceui
node_workspaceui -->|"reads and updates"| node_palacestore
node_palacestore -->|"initializes from"| node_sampledata
node_workspaceui -->|"renders"| node_navigation
node_workspaceui -->|"opens"| node_roomform
node_navigation -->|"selects rooms"| node_palacestore
node_roomform -->|"adds rooms"| node_palacestore
node_workspaceui -->|"opens"| node_anchorform
node_anchorform -->|"adds anchors"| node_palacestore
node_workspaceui -->|"loads scene"| node_scene
node_workspaceui -->|"opens selected anchor"| node_drawer
node_workspaceui -->|"renders"| node_mode
node_drawer -->|"records edits and ratings"| node_palacestore
node_mode -->|"changes mode"| node_palacestore
node_workspaceui -->|"provides"| node_searchinsights
node_scene -->|"reads scene state"| node_palacestore
node_scene -->|"renders anchors"| node_memoryanchor
node_scene -->|"mounts controls"| node_camera
node_camera -->|"reads camera targets"| node_palacestore
node_learner -->|"requests installation"| node_install
node_install -->|"offers install flow"| node_browser
node_offline -.->|"serves fallback"| node_browser

click node_auth "https://github.com/knnagesh78/neuroquest/blob/main/src/components/account/AccountGate.tsx"
click node_firebase "https://github.com/knnagesh78/neuroquest/blob/main/src/lib/firebase.ts"
click node_accountlib "https://github.com/knnagesh78/neuroquest/blob/main/src/lib/account.ts"
click node_sync "https://github.com/knnagesh78/neuroquest/blob/main/src/lib/workspace-cloud.ts"
click node_savequeue "https://github.com/knnagesh78/neuroquest/blob/main/src/lib/save-queue.ts"
click node_accountcontrols "https://github.com/knnagesh78/neuroquest/blob/main/src/components/account/AccountControls.tsx"
click node_accountstate "https://github.com/knnagesh78/neuroquest/blob/main/src/store/useAccountStore.ts"
click node_workspaceui "https://github.com/knnagesh78/neuroquest/blob/main/src/components/NeuroQuest.tsx"
click node_palacestore "https://github.com/knnagesh78/neuroquest/blob/main/src/store/usePalaceStore.ts"
click node_sampledata "https://github.com/knnagesh78/neuroquest/blob/main/src/lib/data.ts"
click node_navigation "https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/Navigation.tsx"
click node_roomform "https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AddRoomModal.tsx"
click node_anchorform "https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AddAnchorModal.tsx"
click node_drawer "https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AnchorDrawer.tsx"
click node_mode "https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/ModeSwitcher.tsx"
click node_searchinsights "https://github.com/knnagesh78/neuroquest/blob/main/src/components/NeuroQuest.tsx"
click node_scene "https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/Scene.tsx"
click node_memoryanchor "https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/MemoryAnchor.tsx"
click node_camera "https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/CameraController.tsx"
click node_install "https://github.com/knnagesh78/neuroquest/blob/main/src/components/pwa/InstallWizard.tsx"
click node_offline "https://github.com/knnagesh78/neuroquest/blob/main/public/sw.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_auth,node_firebase,node_accountlib,node_sync,node_savequeue,node_accountcontrols,node_accountstate,node_browser toneBlue
class node_workspaceui,node_palacestore,node_sampledata,node_navigation,node_roomform,node_firestore toneAmber
class node_anchorform,node_drawer,node_mode,node_searchinsights toneMint
class node_scene,node_memoryanchor,node_camera toneRose
class node_install,node_offline,node_learner,node_firebaseauth toneIndigo
```

## Components

### Account & sync

- [Account gate](https://github.com/knnagesh78/neuroquest/blob/main/src/components/account/AccountGate.tsx): `src/components/account/AccountGate.tsx`
- [Firebase services](https://github.com/knnagesh78/neuroquest/blob/main/src/lib/firebase.ts): `src/lib/firebase.ts`
- [Account helpers](https://github.com/knnagesh78/neuroquest/blob/main/src/lib/account.ts): `src/lib/account.ts`
- [Workspace sync](https://github.com/knnagesh78/neuroquest/blob/main/src/lib/workspace-cloud.ts): `src/lib/workspace-cloud.ts`
- [Save queue](https://github.com/knnagesh78/neuroquest/blob/main/src/lib/save-queue.ts): `src/lib/save-queue.ts`
- [Account controls](https://github.com/knnagesh78/neuroquest/blob/main/src/components/account/AccountControls.tsx): `src/components/account/AccountControls.tsx`
- [Account status](https://github.com/knnagesh78/neuroquest/blob/main/src/store/useAccountStore.ts): `src/store/useAccountStore.ts`

### Palace workspace

- [Workspace shell](https://github.com/knnagesh78/neuroquest/blob/main/src/components/NeuroQuest.tsx): `src/components/NeuroQuest.tsx`
- [Palace state](https://github.com/knnagesh78/neuroquest/blob/main/src/store/usePalaceStore.ts): `src/store/usePalaceStore.ts`
- [Starter palaces](https://github.com/knnagesh78/neuroquest/blob/main/src/lib/data.ts): `src/lib/data.ts`
- [Palace navigation](https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/Navigation.tsx): `src/components/ui/Navigation.tsx`
- [Create palace](https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AddRoomModal.tsx): `src/components/ui/AddRoomModal.tsx`

### Study experience

- [Create anchor](https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AddAnchorModal.tsx): `src/components/ui/AddAnchorModal.tsx`
- [Study drawer](https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/AnchorDrawer.tsx): `src/components/ui/AnchorDrawer.tsx`
- [Study mode](https://github.com/knnagesh78/neuroquest/blob/main/src/components/ui/ModeSwitcher.tsx): `src/components/ui/ModeSwitcher.tsx`
- [Search & insights](https://github.com/knnagesh78/neuroquest/blob/main/src/components/NeuroQuest.tsx): `src/components/NeuroQuest.tsx`

### 3D environment

- [Scene renderer](https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/Scene.tsx): `src/components/three/Scene.tsx`
- [Spatial artifacts](https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/MemoryAnchor.tsx): `src/components/three/MemoryAnchor.tsx`
- [Camera controls](https://github.com/knnagesh78/neuroquest/blob/main/src/components/three/CameraController.tsx): `src/components/three/CameraController.tsx`

### Install & offline

- [Install wizard](https://github.com/knnagesh78/neuroquest/blob/main/src/components/pwa/InstallWizard.tsx): `src/components/pwa/InstallWizard.tsx`
- [Offline worker](https://github.com/knnagesh78/neuroquest/blob/main/public/sw.js): `public/sw.js`

### Other components

- **Learner**
- **Firebase Auth**
- **Cloud Firestore**
- **Browser**

## Connections

- Learner → Account gate: signs in (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Firebase services: initializes (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Account helpers: formats errors (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Firebase Auth: authenticates (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Workspace sync: loads workspace (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Save queue: queues saves (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Palace state: replaces state (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Workspace shell: mounts workspace (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Account controls: renders sync controls (evidence: `src/components/account/AccountGate.tsx`)
- Account gate → Account status: updates status (evidence: `src/components/account/AccountGate.tsx`)
- Workspace sync → Cloud Firestore: reads and writes
- Save queue → Workspace sync: batches saves
- Learner → Workspace shell: uses workspace (evidence: `README.md`)
- Workspace shell → Palace state: reads and updates (evidence: `src/components/NeuroQuest.tsx`)
- Palace state → Starter palaces: initializes from (evidence: `src/store/usePalaceStore.ts`)
- Workspace shell → Palace navigation: renders (evidence: `src/components/NeuroQuest.tsx`)
- Workspace shell → Create palace: opens (evidence: `src/components/NeuroQuest.tsx`)
- Palace navigation → Palace state: selects rooms (evidence: `src/components/NeuroQuest.tsx`)
- Create palace → Palace state: adds rooms (evidence: `src/components/NeuroQuest.tsx`)
- Workspace shell → Create anchor: opens (evidence: `src/components/NeuroQuest.tsx`)
- Create anchor → Palace state: adds anchors (evidence: `src/components/ui/AddAnchorModal.tsx`)
- Workspace shell → Scene renderer: loads scene (evidence: `src/components/NeuroQuest.tsx`)
- Workspace shell → Study drawer: opens selected anchor (evidence: `src/components/NeuroQuest.tsx`)
- Workspace shell → Study mode: renders (evidence: `src/components/NeuroQuest.tsx`)
- Study drawer → Palace state: records edits and ratings (evidence: `src/components/ui/AnchorDrawer.tsx`)
- Study mode → Palace state: changes mode (evidence: `src/components/NeuroQuest.tsx`)
- Workspace shell → Search & insights: provides (evidence: `README.md`)
- Scene renderer → Palace state: reads scene state (evidence: `src/components/three/Scene.tsx`)
- Scene renderer → Spatial artifacts: renders anchors (evidence: `src/components/three/Scene.tsx`)
- Scene renderer → Camera controls: mounts controls (evidence: `src/components/three/Scene.tsx`)
- Camera controls → Palace state: reads camera targets (evidence: `src/components/three/CameraController.tsx`)
- Learner → Install wizard: requests installation (evidence: `README.md`)
- Install wizard → Browser: offers install flow (evidence: `README.md`)
- Offline worker → Browser: serves fallback
