# niravrvaghasiya/playtolearnml architecture

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

- Interactive diagram: https://gitdiagram.com/niravrvaghasiya/playtolearnml
- Repository: https://github.com/niravrvaghasiya/playtolearnml

## Overview

GameML is a browser-based machine-learning learning product: players choose a game, manipulate an algorithm through visual or code controls, and receive live metrics and explanations. The README documents all 14 games, six subject categories, a concept library, local progression, and optional Supabase progression support. The tree and sampled source support the shared engine, code execution, TensorFlow.js lifecycle, and representative game logic; unsampled game wiring is not expanded into speculative call chains.

Main entry points: [`src/games/registry.ts`](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/registry.ts) (Game registry), [`src/engine/GameShell.tsx`](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/GameShell.tsx) (Game shell), [`src/games/GameMount.tsx`](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/GameMount.tsx) (Game mount), [`src/engine/progression.ts`](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/progression.ts) (Progression engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_game_pages["Game routes<br/>[page.tsx]"]
  node_concept_pages["Concept library"]
  node_game_mount["Game mount<br/>[GameMount.tsx]"]
  node_game_registry["Game registry<br/>[registry.ts]"]
  node_shared_ui["Shared UI<br/>[index.ts]"]
end

subgraph group_runtime["Shared runtime"]
  node_game_shell["Game shell<br/>[GameShell.tsx]"]
  node_code_lane["Code lane<br/>[useCodeLane.ts]"]
  node_model_runtime["Model lifecycle<br/>[useModel.ts]"]
end

subgraph group_curriculum["Game curriculum"]
  node_data_games["Data preparation"]
  node_supervised_games["Supervised learning"]
  node_neural_games["Neural networks"]
  node_optimization_games["Optimization tuning"]
  node_unsupervised_games["Unsupervised learning"]
  node_rl_games["Reinforcement learning"]
end

subgraph group_progress["Learning progress"]
  node_progression["Progression engine<br/>[progression.ts]"]
  node_local_progress[("Browser progress<br/>[progression.ts]")]
end

node_learner(("Learner"))
node_supabase[("Supabase")]

node_learner -->|"chooses game"| node_game_pages
node_game_pages -->|"loads game"| node_game_mount
node_game_mount -->|"selects entry"| node_game_registry
node_learner -->|"reads concepts"| node_concept_pages
node_game_mount -->|"runs session"| node_game_shell
node_game_shell -->|"renders controls"| node_shared_ui
node_game_shell -->|"offers code lane"| node_code_lane
node_game_shell -->|"records results"| node_progression
node_code_lane -.->|"runs ML code"| node_model_runtime
node_game_registry -->|"exposes games"| node_data_games
node_game_registry -->|"exposes games"| node_supervised_games
node_game_registry -->|"exposes games"| node_neural_games
node_game_registry -->|"exposes games"| node_optimization_games
node_game_registry -->|"exposes games"| node_unsupervised_games
node_game_registry -->|"exposes games"| node_rl_games
node_progression -->|"saves locally"| node_local_progress
node_progression -.->|"syncs progress"| node_supabase

click node_game_pages "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/app/play/%5Bslug%5D/page.tsx"
click node_concept_pages "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/app/concepts"
click node_game_mount "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/GameMount.tsx"
click node_game_registry "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/registry.ts"
click node_shared_ui "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/components/index.ts"
click node_game_shell "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/GameShell.tsx"
click node_code_lane "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/useCodeLane.ts"
click node_model_runtime "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/useModel.ts"
click node_progression "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/progression.ts"
click node_local_progress "https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/progression.ts"
click node_data_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/data-detox"
click node_supervised_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/sort-it-arcade"
click node_neural_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/neuron-forge"
click node_optimization_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/gradient-descent-skier"
click node_unsupervised_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/k-means-territory-wars"
click node_rl_games "https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/agent-academy"

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_game_pages,node_concept_pages,node_game_mount,node_game_registry,node_shared_ui toneBlue
class node_game_shell,node_code_lane,node_model_runtime,node_supabase toneAmber
class node_data_games,node_supervised_games,node_neural_games,node_optimization_games,node_unsupervised_games,node_rl_games toneMint
class node_progression,node_local_progress toneRose
class node_learner toneIndigo
```

## Components

### Web experience

- [Game routes](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/app/play/%5Bslug%5D/page.tsx): `src/app/play/[slug]/page.tsx`
- [Concept library](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/app/concepts): `src/app/concepts`
- [Game mount](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/GameMount.tsx): `src/games/GameMount.tsx`
- [Game registry](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/games/registry.ts): `src/games/registry.ts`
- [Shared UI](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/components/index.ts): `src/components/index.ts`

### Shared runtime

- [Game shell](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/GameShell.tsx): `src/engine/GameShell.tsx`
- [Code lane](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/useCodeLane.ts): `src/engine/useCodeLane.ts`
- [Model lifecycle](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/useModel.ts): `src/engine/useModel.ts`

### Game curriculum

- [Data preparation](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/data-detox): `src/games/data-detox`
- [Supervised learning](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/sort-it-arcade): `src/games/sort-it-arcade`
- [Neural networks](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/neuron-forge): `src/games/neuron-forge`
- [Optimization tuning](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/gradient-descent-skier): `src/games/gradient-descent-skier`
- [Unsupervised learning](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/k-means-territory-wars): `src/games/k-means-territory-wars`
- [Reinforcement learning](https://github.com/niravrvaghasiya/playtolearnml/tree/main/src/games/agent-academy): `src/games/agent-academy`

### Learning progress

- [Progression engine](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/progression.ts): `src/engine/progression.ts`
- [Browser progress](https://github.com/niravrvaghasiya/playtolearnml/blob/main/src/engine/progression.ts): `src/engine/progression.ts`

### Other components

- **Learner**
- **Supabase**

## Connections

- Learner → Game routes: chooses game
- Game routes → Game mount: loads game
- Game mount → Game registry: selects entry
- Learner → Concept library: reads concepts
- Game mount → Game shell: runs session
- Game shell → Shared UI: renders controls
- Game shell → Code lane: offers code lane
- Game shell → Progression engine: records results
- Code lane → Model lifecycle: runs ML code
- Game registry → Data preparation: exposes games
- Game registry → Supervised learning: exposes games
- Game registry → Neural networks: exposes games
- Game registry → Optimization tuning: exposes games
- Game registry → Unsupervised learning: exposes games
- Game registry → Reinforcement learning: exposes games
- Progression engine → Browser progress: saves locally
- Progression engine → Supabase: syncs progress