# devanithimaran10/sphere-trainer architecture

> Architecture diagram of the GitHub repository devanithimaran10/sphere-trainer, 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/devanithimaran10/sphere-trainer
- Repository: https://github.com/devanithimaran10/sphere-trainer

## Overview

Neuro-Adapt is a browser-based cognitive-motor trainer with two connected experiences: Sphere Trainer sessions and the NeuroPlay cognitive-games hub. Players train in adaptive tasks, receive scores and progress summaries, and can review history or adjust accessibility and pacing. The main session store coordinates Sphere scoring and adaptive control; NeuroPlay has a separate profile/session store and scoring pipeline. The README documents modes and capabilities not all individually sampled; unsampled page and game implementations are represented by their exact source paths, with only documented or indexed relationships shown.

Main entry points: [`src/App.tsx`](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/App.tsx) (App shell), [`src/store/useGameStore.ts`](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useGameStore.ts) (Session state), [`src/neuroplay/NeuroPlayApp.tsx`](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/NeuroPlayApp.tsx) (NeuroPlay app), [`src/neuroplay/store/useNeuroPlayStore.ts`](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/store/useNeuroPlayStore.ts) (Profiles and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application shell"]
  node_app["App shell<br/>[App.tsx]"]
end

subgraph group_sphere["Sphere training"]
  node_scene["3D scene<br/>[Scene.tsx]"]
  node_hud["Training HUD<br/>[PlayingHUD.tsx]"]
  node_mode_definitions["Training modes<br/>[modes.ts]"]
  node_mini_router["Mini-game router<br/>[MiniGameRouter.tsx]"]
  node_mini_games["Mini-games"]
  node_game_store["Session state<br/>[useGameStore.ts]"]
  node_session_lifecycle["Session recovery"]
end

subgraph group_adaptive["Scoring and adaptation"]
  node_ai_simulation["AI warm start<br/>[simulate.ts]"]
  node_state_estimator["State estimator<br/>[stateEstimator.ts]"]
  node_rl_controller["RL controller<br/>[rlController.ts]"]
  node_safety_layer["Safety layer<br/>[safetyLayer.ts]"]
  node_cognitive_scoring["Cognitive profile scoring"]
  node_progress_predictor["Progress predictor"]
  node_neuroplay_scoring["Game scoring<br/>[scoringEngine.ts]"]
  node_fatigue["Fatigue estimator<br/>[fatigueEngine.ts]"]
  node_adaptive_engine["Difficulty adaptation<br/>[adaptiveEngine.ts]"]
  node_recommendations["Recommendations"]
end

subgraph group_neuroplay["NeuroPlay hub"]
  node_neuroplay_app["NeuroPlay app<br/>[NeuroPlayApp.tsx]"]
  node_neuroplay_pages["Hub pages"]
  node_neuroplay_games["Cognitive games"]
  node_training_summary["Session summary"]
end

subgraph group_state["Profiles and history"]
  node_settings["Accessibility settings"]
  node_history[("Session history<br/>[useHistoryStore.ts]")]
  node_neuroplay_store[("Profiles and sessions")]
end

node_player(("Player"))

node_player -->|"starts training"| node_app
node_app -->|"renders"| node_scene
node_app -->|"renders"| node_hud
node_app -->|"reads preferences"| node_settings
node_app -->|"reads phase"| node_game_store
node_app -->|"bootstraps"| node_ai_simulation
node_app -->|"checks recovery"| node_session_lifecycle
node_app -->|"switches to"| node_neuroplay_app
node_scene -->|"reads game state"| node_game_store
node_scene -.->|"renders sphere"| node_mini_games
node_hud -->|"reads and updates"| node_game_store
node_hud -->|"uses modes"| node_mode_definitions
node_mini_router -->|"routes games"| node_mini_games
node_mini_router -->|"reads game state"| node_game_store
node_game_store -->|"estimates state"| node_state_estimator
node_game_store -->|"chooses and updates"| node_rl_controller
node_game_store -->|"vets action"| node_safety_layer
node_game_store -->|"records results"| node_history
node_app -->|"pauses on background"| node_session_lifecycle
node_app -->|"applies display settings"| node_settings
node_neuroplay_app -->|"reads hub state"| node_neuroplay_store
node_neuroplay_app -->|"routes pages"| node_neuroplay_pages
node_neuroplay_app -->|"renders games"| node_neuroplay_games
node_neuroplay_store -.->|"stores game results"| node_neuroplay_games
node_neuroplay_store -.->|"seeds demo sessions"| node_neuroplay_scoring
node_neuroplay_scoring -->|"shares scoring helpers"| node_fatigue
node_adaptive_engine -->|"uses scoring"| node_neuroplay_scoring
node_recommendations -->|"uses adaptation"| node_adaptive_engine
node_recommendations -->|"uses fatigue"| node_fatigue
node_training_summary -->|"reads session data"| node_neuroplay_store
node_training_summary -->|"calculates fatigue"| node_fatigue
node_training_summary -->|"scores session"| node_neuroplay_scoring
node_cognitive_scoring -->|"reads sessions"| node_history
node_neuroplay_pages -.->|"shows profile"| node_cognitive_scoring
node_player -->|"trains and reviews"| node_neuroplay_app

click node_app "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/App.tsx"
click node_scene "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/Scene.tsx"
click node_hud "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/PlayingHUD.tsx"
click node_mode_definitions "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/modes.ts"
click node_mini_router "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/MiniGameRouter.tsx"
click node_mini_games "https://github.com/devanithimaran10/sphere-trainer/tree/main/src/components/games"
click node_game_store "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useGameStore.ts"
click node_session_lifecycle "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useSessionLifecycle.ts"
click node_settings "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useSettingsStore.ts"
click node_ai_simulation "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/simulate.ts"
click node_state_estimator "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/stateEstimator.ts"
click node_rl_controller "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/rlController.ts"
click node_safety_layer "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/safetyLayer.ts"
click node_cognitive_scoring "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/cognitiveScoringEngine.ts"
click node_progress_predictor "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/progressPredictor.ts"
click node_history "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useHistoryStore.ts"
click node_neuroplay_app "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/NeuroPlayApp.tsx"
click node_neuroplay_pages "https://github.com/devanithimaran10/sphere-trainer/tree/main/src/neuroplay/pages"
click node_neuroplay_games "https://github.com/devanithimaran10/sphere-trainer/tree/main/src/neuroplay/games"
click node_neuroplay_store "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/store/useNeuroPlayStore.ts"
click node_neuroplay_scoring "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/scoringEngine.ts"
click node_fatigue "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/fatigueEngine.ts"
click node_adaptive_engine "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/adaptiveEngine.ts"
click node_recommendations "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/recommendationEngine.ts"
click node_training_summary "https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/components/TrainingSessionSummary.tsx"

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 toneBlue
class node_scene,node_hud,node_mode_definitions,node_mini_router,node_mini_games,node_game_store,node_session_lifecycle toneAmber
class node_ai_simulation,node_state_estimator,node_rl_controller,node_safety_layer,node_cognitive_scoring,node_progress_predictor,node_neuroplay_scoring,node_fatigue,node_adaptive_engine,node_recommendations toneMint
class node_neuroplay_app,node_neuroplay_pages,node_neuroplay_games,node_training_summary toneRose
class node_settings,node_history,node_neuroplay_store,node_player toneIndigo
```

## Components

### Application shell

- [App shell](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/App.tsx): `src/App.tsx`

### Sphere training

- [3D scene](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/Scene.tsx): `src/components/Scene.tsx`
- [Training HUD](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/PlayingHUD.tsx): `src/components/hud/PlayingHUD.tsx`
- [Training modes](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/modes.ts): `src/components/hud/modes.ts`
- [Mini-game router](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/components/hud/MiniGameRouter.tsx): `src/components/hud/MiniGameRouter.tsx`
- [Mini-games](https://github.com/devanithimaran10/sphere-trainer/tree/main/src/components/games): `src/components/games`
- [Session state](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useGameStore.ts): `src/store/useGameStore.ts`
- [Session recovery](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useSessionLifecycle.ts): `src/store/useSessionLifecycle.ts`

### Scoring and adaptation

- [AI warm start](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/simulate.ts): `src/ai/simulate.ts`
- [State estimator](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/stateEstimator.ts): `src/ai/stateEstimator.ts`
- [RL controller](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/rlController.ts): `src/ai/rlController.ts`
- [Safety layer](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/safetyLayer.ts): `src/ai/safetyLayer.ts`
- [Cognitive profile scoring](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/cognitiveScoringEngine.ts): `src/ai/cognitiveScoringEngine.ts`
- [Progress predictor](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/ai/progressPredictor.ts): `src/ai/progressPredictor.ts`
- [Game scoring](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/scoringEngine.ts): `src/neuroplay/engine/scoringEngine.ts`
- [Fatigue estimator](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/fatigueEngine.ts): `src/neuroplay/engine/fatigueEngine.ts`
- [Difficulty adaptation](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/adaptiveEngine.ts): `src/neuroplay/engine/adaptiveEngine.ts`
- [Recommendations](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/engine/recommendationEngine.ts): `src/neuroplay/engine/recommendationEngine.ts`

### NeuroPlay hub

- [NeuroPlay app](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/NeuroPlayApp.tsx): `src/neuroplay/NeuroPlayApp.tsx`
- [Hub pages](https://github.com/devanithimaran10/sphere-trainer/tree/main/src/neuroplay/pages): `src/neuroplay/pages`
- [Cognitive games](https://github.com/devanithimaran10/sphere-trainer/tree/main/src/neuroplay/games): `src/neuroplay/games`
- [Session summary](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/components/TrainingSessionSummary.tsx): `src/neuroplay/components/TrainingSessionSummary.tsx`

### Profiles and history

- [Accessibility settings](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useSettingsStore.ts): `src/store/useSettingsStore.ts`
- [Session history](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/store/useHistoryStore.ts): `src/store/useHistoryStore.ts`
- [Profiles and sessions](https://github.com/devanithimaran10/sphere-trainer/blob/main/src/neuroplay/store/useNeuroPlayStore.ts): `src/neuroplay/store/useNeuroPlayStore.ts`

### Other components

- **Player**

## Connections

- Player → App shell: starts training
- App shell → 3D scene: renders (evidence: `src/App.tsx`)
- App shell → Training HUD: renders (evidence: `src/App.tsx`)
- App shell → Accessibility settings: reads preferences (evidence: `src/App.tsx`)
- App shell → Session state: reads phase (evidence: `src/App.tsx`)
- App shell → AI warm start: bootstraps (evidence: `src/App.tsx`)
- App shell → Session recovery: checks recovery (evidence: `src/App.tsx`)
- App shell → NeuroPlay app: switches to (evidence: `src/App.tsx`)
- 3D scene → Session state: reads game state (evidence: `src/components/Scene.tsx`)
- 3D scene → Mini-games: renders sphere
- Training HUD → Session state: reads and updates (evidence: `src/components/hud/PlayingHUD.tsx`)
- Training HUD → Training modes: uses modes (evidence: `src/components/hud/PlayingHUD.tsx`)
- Mini-game router → Mini-games: routes games (evidence: `src/components/hud/MiniGameRouter.tsx`)
- Mini-game router → Session state: reads game state (evidence: `src/components/hud/MiniGameRouter.tsx`)
- Session state → State estimator: estimates state (evidence: `src/store/useGameStore.ts`)
- Session state → RL controller: chooses and updates (evidence: `src/store/useGameStore.ts`)
- Session state → Safety layer: vets action (evidence: `src/store/useGameStore.ts`)
- Session state → Session history: records results (evidence: `src/store/useGameStore.ts`)
- App shell → Session recovery: pauses on background (evidence: `src/App.tsx`)
- App shell → Accessibility settings: applies display settings (evidence: `src/App.tsx`)
- NeuroPlay app → Profiles and sessions: reads hub state (evidence: `src/neuroplay/NeuroPlayApp.tsx`)
- NeuroPlay app → Hub pages: routes pages (evidence: `src/neuroplay/NeuroPlayApp.tsx`)
- NeuroPlay app → Cognitive games: renders games (evidence: `src/neuroplay/NeuroPlayApp.tsx`)
- Profiles and sessions → Cognitive games: stores game results
- Profiles and sessions → Game scoring: seeds demo sessions
- Game scoring → Fatigue estimator: shares scoring helpers (evidence: `src/neuroplay/engine/fatigueEngine.ts`)
- Difficulty adaptation → Game scoring: uses scoring (evidence: `src/neuroplay/engine/adaptiveEngine.ts`)
- Recommendations → Difficulty adaptation: uses adaptation (evidence: `src/neuroplay/engine/recommendationEngine.ts`)
- Recommendations → Fatigue estimator: uses fatigue (evidence: `src/neuroplay/engine/recommendationEngine.ts`)
- Session summary → Profiles and sessions: reads session data (evidence: `src/neuroplay/components/TrainingSessionSummary.tsx`)
- Session summary → Fatigue estimator: calculates fatigue (evidence: `src/neuroplay/components/TrainingSessionSummary.tsx`)
- Session summary → Game scoring: scores session (evidence: `src/neuroplay/components/TrainingSessionSummary.tsx`)
- Cognitive profile scoring → Session history: reads sessions (evidence: `src/ai/cognitiveScoringEngine.ts`)
- Hub pages → Cognitive profile scoring: shows profile
- Player → NeuroPlay app: trains and reviews
