# kajamaqbool/steady-gaze-buddy-main architecture

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

- Interactive diagram: https://gitdiagram.com/kajamaqbool/steady-gaze-buddy-main
- Repository: https://github.com/kajamaqbool/steady-gaze-buddy-main

## Overview

DysLex Shield is a child-friendly reading adventure that captures browser-based gaze data and presents screening signals to adults, not a diagnosis. Its main journey runs from authenticated profile selection through camera setup, five-point calibration, the reading adventure and mini-games, then local analysis and export. A separate optional branch streams session data to an authenticated STOMP backend and displays returned results. The graph combines README-documented capabilities with sampled source references; several implementation details, including individual adventure stages and export internals, were not sampled.

Main entry points: [`src/pages/Index.tsx`](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/pages/Index.tsx) (Adventure flow), [`src/api/wsClient.ts`](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/wsClient.ts) (STOMP client), [`src/components/AuthGuard.tsx`](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/AuthGuard.tsx) (Auth boundary), [`src/components/SteadyReaderGame.tsx`](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/SteadyReaderGame.tsx) (Reading adventure)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and access"]
  node_app["Routes and providers<br/>[App.tsx]"]
  node_authguard["Auth boundary<br/>[AuthGuard.tsx]"]
  node_authcontext["Auth state<br/>[AuthContext.tsx]"]
  node_authservice["Auth requests<br/>[authService.ts]"]
end

subgraph group_adventure["Reading adventure"]
  node_index["Adventure flow<br/>[Index.tsx]"]
  node_profiles["Explorer profiles"]
  node_profilestore[("Local profile store<br/>[profileStore.ts]")]
  node_welcome["Adventure welcome"]
  node_calibration["Gaze calibration"]
  node_game["Reading adventure"]
  node_stages["Mini-game stages<br/>[WordHuntStage.tsx]"]
  node_mascot["Lumi mascot<br/>[Mascot.tsx]"]
  node_end["Completion and export<br/>[EndScreen.tsx]"]
end

subgraph group_tracking["Gaze capture"]
  node_camera["Camera and Face Mesh<br/>[useEyeTracking.ts]"]
  node_preview["Camera preview<br/>[CameraPreview.tsx]"]
  node_gazedata["Gaze session data<br/>[gaze.ts]"]
  node_processing["Gaze processing"]
end

subgraph group_analysis["Analysis and results"]
  node_features["Feature detection"]
  node_fixations["Fixation detection"]
  node_saccades["Saccade detection"]
  node_results["Result interpretation<br/>[resultProcessor.ts]"]
  node_history[("Result history")]
end

subgraph group_streaming["Backend streaming"]
  node_store[("Session and stream state<br/>[gazeStore.ts]")]
  node_session["Session lifecycle<br/>[sessionManager.ts]"]
  node_ws["STOMP client<br/>[wsClient.ts]"]
  node_streamhooks["Connection and responses"]
end

node_reader(("Child / adult"))
node_authbackend{{"Auth API"}}
node_mlbackend{{"Gaze and ML backend"}}

node_reader -->|"opens app"| node_app
node_app -->|"protects route"| node_authguard
node_authguard -->|"checks access"| node_authcontext
node_authcontext -->|"requests auth"| node_authservice
node_authservice -->|"calls REST API"| node_authbackend
node_authguard -->|"admits signed-in user"| node_index
node_reader -->|"starts adventure"| node_index
node_index -->|"shows profiles"| node_profiles
node_profiles -.->|"persists profiles"| node_profilestore
node_index -->|"shows welcome"| node_welcome
node_index -->|"starts capture"| node_camera
node_camera -.->|"supplies camera view"| node_preview
node_camera -->|"produces gaze points"| node_gazedata
node_index -->|"opens calibration"| node_calibration
node_calibration -.->|"calibrates gaze"| node_gazedata
node_index -->|"starts reading"| node_game
node_game -->|"offers mini-games"| node_stages
node_game -.->|"features Lumi"| node_mascot
node_index -->|"shows completion"| node_end
node_end -->|"runs local analysis"| node_processing
node_processing -->|"extracts features"| node_features
node_features -->|"uses detector"| node_fixations
node_features -->|"uses detector"| node_saccades
node_end -->|"offers JSON export"| node_reader
node_index -.->|"optionally connects"| node_streamhooks
node_streamhooks -->|"manages connection"| node_ws
node_ws -->|"refreshes token"| node_authservice
node_session -->|"controls session"| node_ws
node_session -->|"updates session state"| node_store
node_ws -->|"streams gaze data"| node_mlbackend
node_mlbackend -->|"returns results"| node_ws
node_streamhooks -->|"updates stream state"| node_store
node_ws -.->|"passes ML results"| node_results
node_results -.->|"records results"| node_history

click node_app "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/App.tsx"
click node_authguard "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/AuthGuard.tsx"
click node_authcontext "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/context/AuthContext.tsx"
click node_authservice "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/authService.ts"
click node_index "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/pages/Index.tsx"
click node_profiles "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/ChildProfileSelect.tsx"
click node_profilestore "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/adventure/profileStore.ts"
click node_welcome "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/AdventureWelcome.tsx"
click node_calibration "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/CalibrationScreen.tsx"
click node_game "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/SteadyReaderGame.tsx"
click node_stages "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/WordHuntStage.tsx"
click node_mascot "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/Mascot.tsx"
click node_end "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/EndScreen.tsx"
click node_camera "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useEyeTracking.ts"
click node_preview "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/CameraPreview.tsx"
click node_gazedata "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/types/gaze.ts"
click node_processing "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useGazeProcessing.ts"
click node_features "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/featureExtractionPhase3.ts"
click node_fixations "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/fixationDetectionEnhanced.ts"
click node_saccades "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/saccadeDetectionEnhanced.ts"
click node_results "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/resultProcessor.ts"
click node_history "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/resultHistoryManager.ts"
click node_store "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/store/gazeStore.ts"
click node_session "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/sessionManager.ts"
click node_ws "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/wsClient.ts"
click node_streamhooks "https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useWebSocketConnection.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_authguard,node_authcontext,node_authservice toneBlue
class node_index,node_profiles,node_profilestore,node_welcome,node_calibration,node_game,node_stages,node_mascot,node_end toneAmber
class node_camera,node_preview,node_gazedata,node_processing,node_authbackend toneMint
class node_features,node_fixations,node_saccades,node_results,node_history toneRose
class node_store,node_session,node_ws,node_streamhooks,node_reader,node_mlbackend toneIndigo
```

## Components

### App and access

- [Routes and providers](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/App.tsx): `src/App.tsx`
- [Auth boundary](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/AuthGuard.tsx): `src/components/AuthGuard.tsx`
- [Auth state](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/context/AuthContext.tsx): `src/context/AuthContext.tsx`
- [Auth requests](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/authService.ts): `src/api/authService.ts`

### Reading adventure

- [Adventure flow](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/pages/Index.tsx): `src/pages/Index.tsx`
- [Explorer profiles](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/ChildProfileSelect.tsx): `src/components/ChildProfileSelect.tsx`
- [Local profile store](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/adventure/profileStore.ts): `src/adventure/profileStore.ts`
- [Adventure welcome](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/AdventureWelcome.tsx): `src/components/AdventureWelcome.tsx`
- [Gaze calibration](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/CalibrationScreen.tsx): `src/components/CalibrationScreen.tsx`
- [Reading adventure](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/SteadyReaderGame.tsx): `src/components/SteadyReaderGame.tsx`
- [Mini-game stages](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/WordHuntStage.tsx): `src/components/WordHuntStage.tsx`
- [Lumi mascot](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/Mascot.tsx): `src/components/Mascot.tsx`
- [Completion and export](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/EndScreen.tsx): `src/components/EndScreen.tsx`

### Gaze capture

- [Camera and Face Mesh](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useEyeTracking.ts): `src/hooks/useEyeTracking.ts`
- [Camera preview](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/components/CameraPreview.tsx): `src/components/CameraPreview.tsx`
- [Gaze session data](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/types/gaze.ts): `src/types/gaze.ts`
- [Gaze processing](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useGazeProcessing.ts): `src/hooks/useGazeProcessing.ts`

### Analysis and results

- [Feature detection](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/featureExtractionPhase3.ts): `src/lib/featureExtractionPhase3.ts`
- [Fixation detection](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/fixationDetectionEnhanced.ts): `src/lib/fixationDetectionEnhanced.ts`
- [Saccade detection](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/lib/saccadeDetectionEnhanced.ts): `src/lib/saccadeDetectionEnhanced.ts`
- [Result interpretation](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/resultProcessor.ts): `src/api/resultProcessor.ts`
- [Result history](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/resultHistoryManager.ts): `src/api/resultHistoryManager.ts`

### Backend streaming

- [Session and stream state](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/store/gazeStore.ts): `src/store/gazeStore.ts`
- [Session lifecycle](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/sessionManager.ts): `src/api/sessionManager.ts`
- [STOMP client](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/api/wsClient.ts): `src/api/wsClient.ts`
- [Connection and responses](https://github.com/kajamaqbool/steady-gaze-buddy-main/blob/main/src/hooks/useWebSocketConnection.ts): `src/hooks/useWebSocketConnection.ts`

### Other components

- **Child / adult**
- **Auth API**
- **Gaze and ML backend**

## Connections

- Child / adult → Routes and providers: opens app (evidence: `README.md`)
- Routes and providers → Auth boundary: protects route (evidence: `src/App.tsx`)
- Auth boundary → Auth state: checks access (evidence: `src/components/AuthGuard.tsx`)
- Auth state → Auth requests: requests auth (evidence: `src/context/AuthContext.tsx`)
- Auth requests → Auth API: calls REST API (evidence: `README.md`)
- Auth boundary → Adventure flow: admits signed-in user (evidence: `src/App.tsx`)
- Child / adult → Adventure flow: starts adventure (evidence: `README.md`)
- Adventure flow → Explorer profiles: shows profiles (evidence: `src/pages/Index.tsx`)
- Explorer profiles → Local profile store: persists profiles
- Adventure flow → Adventure welcome: shows welcome (evidence: `src/pages/Index.tsx`)
- Adventure flow → Camera and Face Mesh: starts capture (evidence: `src/pages/Index.tsx`)
- Camera and Face Mesh → Camera preview: supplies camera view
- Camera and Face Mesh → Gaze session data: produces gaze points (evidence: `README.md`)
- Adventure flow → Gaze calibration: opens calibration (evidence: `src/pages/Index.tsx`)
- Gaze calibration → Gaze session data: calibrates gaze
- Adventure flow → Reading adventure: starts reading (evidence: `src/pages/Index.tsx`)
- Reading adventure → Mini-game stages: offers mini-games (evidence: `README.md`)
- Reading adventure → Lumi mascot: features Lumi
- Adventure flow → Completion and export: shows completion (evidence: `src/pages/Index.tsx`)
- Completion and export → Gaze processing: runs local analysis (evidence: `README.md`)
- Gaze processing → Feature detection: extracts features (evidence: `src/hooks/useGazeProcessing.ts`)
- Feature detection → Fixation detection: uses detector
- Feature detection → Saccade detection: uses detector
- Completion and export → Child / adult: offers JSON export (evidence: `README.md`)
- Adventure flow → Connection and responses: optionally connects (evidence: `README.md`)
- Connection and responses → STOMP client: manages connection (evidence: `src/hooks/useWebSocketConnection.ts`)
- STOMP client → Auth requests: refreshes token (evidence: `src/api/wsClient.ts`)
- Session lifecycle → STOMP client: controls session (evidence: `src/api/sessionManager.ts`)
- Session lifecycle → Session and stream state: updates session state (evidence: `src/api/sessionManager.ts`)
- STOMP client → Gaze and ML backend: streams gaze data (evidence: `README.md`)
- Gaze and ML backend → STOMP client: returns results (evidence: `README.md`)
- Connection and responses → Session and stream state: updates stream state (evidence: `src/hooks/useWebSocketConnection.ts`)
- STOMP client → Result interpretation: passes ML results
- Result interpretation → Result history: records results
