Mind Gym Whitepaper

Browser-native memory training, presented as a systems-design case study

Mind Gym is a zero-dependency memory training PWA for the open web: no backend, no runtime framework, no account wall, and no hidden infrastructure. This site treats the project as both a playable product and a technical argument. The documentation leads, then the demo backs the claims.

Read the thesisStart with product intent, operating constraints, and the architectural claim.Inspect the systemMove from the high-level map into state, offline delivery, and module boundaries.Open the playable buildUse the game as evidence after the docs have established what matters.

Review packet

• Product claim: short-session training can stay useful without backend dependence.
• Engineering claim: disciplined state ownership and deep modules create leverage in a small JavaScript codebase.
• Operational claim: static hosting, local ownership of progress, and offline delivery can be enough for a serious product.

Why this site exists

Senior engineers, strict reviewers, and contributors should be able to trace every major claim back to concrete files such as app.js, src/game-state.js, src/game-manager.js, src/storage.js, and sw.js.

System leverage at a glance

Signal	Why it matters	Primary evidence
Zero runtime dependencies	The app ships as HTML, CSS, and browser-native JavaScript, so source-to-runtime mapping stays unusually direct.	index.html, app.js, src/*.js
Three-layer state model	Settings, GameState, and ModeState separate durable preferences from live control and specialized mode workflows.	src/settings-manager.js, src/game-state.js, src/nback-state.js, src/recall-state.js
Deep modules in hotspots	Complex areas stay locally understandable instead of dissolving into one giant coordinator.	src/game-manager.js, src/modal-manager.js, src/ui/renderer.js, src/pipeline/win-pipeline.js
Offline-first delivery	Short sessions remain resilient even when connectivity is weak or absent after first load.	sw.js, manifest.webmanifest, src/storage.js
Bilingual docs shell	Core architectural claims remain readable in English and Chinese without splitting the story.	docs/en/*, docs/zh/*

Reading routes

For strict reviewers

Start with Project Thesis

Continue with System Overview, then Module Catalog.

For senior GitHub developers

Start with State Architecture

Continue with PWA and Offline Strategy, then Getting Started.

For new contributors

Start with Learning Path

Continue with Getting Started, then the OpenSpec files in the repository.

For product-minded readers

Start with Project Thesis

Continue with References and Related Work to place the product choices in context.

Capability surface

Training surface	What it trains	Supporting system
Classic matching	Recognition, pair association, pacing	Core board loop, scoring, stats
Countdown mode	Time-budgeted play under pressure	Timer orchestration, score persistence
Daily challenge	Deterministic repeatable sessions	Date seeding, storage, comparison logic
N-back	Working-memory load and response timing	Mode-specific state and training logic
Delayed recall	Post-session recognition testing	Recall state, win pipeline, scoring
Long-term progression	Repeat use over novelty	Achievements, adaptive rating, FSRS-backed mastery

What this whitepaper covers

1. Product intent: why Mind Gym is framed as a serious small system rather than a toy demo.
2. Architecture: how runtime modules, persistence, and offline behavior cooperate.
3. Contributor leverage: where to start, what to read first, and how to verify changes safely.
4. Research context: which ideas come from cognitive training patterns and which come from web engineering practice.

Editorial note

This site is intentionally opinionated. It favors grounded claims over hype, concrete file references over architecture theater, and implementation leverage over novelty for novelty's sake.