System Architecture - BrainyPlayLab
🧠 BrainyPlayLab Docs
System Architecture

BrainyPlayLab Core

High-level overview of the application folder structure, data flow, state management, and routing systems.

description Executive Summary

BrainyPlayLab is a cognitive training application built as a Vite + JavaScript + Tailwind CSS single-page app, wrapped with Capacitor for Android deployment. It targets processing speed, attention, inhibitory control, working memory, and cognitive flexibility through four distinct game modes.

Core Loop

🏠 Home
→
🎮 Select Mode
→
⚙️ Configure
→
▶️ Play
→
📊 Results
→
📈 Profile
↺

What "BrainyPlayLab" Means

"BrainyPlayLab" refers to the core mechanic of the Classic Grid mode: the player must match a text prompt to the correct image from a grid of distractors. The name extends to the broader product brand.

account_tree Architecture Map

Folder Structure

Folder Responsibility
js/ App shell, screens, services, store, game wrappers, progression
js/screens/ 17 screen classes (Home, Game, Results, Settings…)
js/services/ 19 service modules (scoring, metrics, auth, haptics…)
js/game/ Game engine wrappers (YesNo, PathMemory) + pause controller
js/progression/ Leveling system (v3 Neural Synergy engine)
games/classic/ Classic Grid engine + dataset
games/quickcalc/ QuickCalc 2.0 engine
games/BrainyPlayLab/ Shared dataset, audio, dataLoader, image assets
public/assets/ i18n JSON files, images, data files
android/ Capacitor Android platform

State Management

  • Pattern: Observable Store wrapping localStorage (store.js)
  • Three domains: Settings, Profile, Sessions
  • Per-user keys: bpl_profile_{uid}, bpl_settings_{uid}, bpl_sessions_{uid}
  • Caching: In-memory cache for sessions and profile
  • Guest → User migration: Automatic data transfer on first login

Routing

Type: Hash-based SPA router (router.js)

Navigation: window.app.navigateTo(ROUTES.X) → router.navigate()

State passing: One-shot router._state payload consumed by router.getState()

Critical Module Map

Module File Purpose
App Shell app.js Boot, routing, global click handler
Store store.js localStorage persistence layer
Classic Engine ClassicEngine.js Grid-match cognition (865 lines)
YesNo Engine yesnoEngine.js Yes/No pattern matching (649 lines)
PathMemory pathMemoryEngine.js Visuo-spatial memory (1366 lines)
QuickCalc QuickCalcEngine.js Arithmetic cognition (547 lines)
Scoring ScoringEngine.js PSI/ICI/ASI/WMI/FI → NeuroScore
Metrics metricsService.js 5-pillar cognitive analytics
Progression ProgressionEngine.js Neural Synergy v3 dual-currency

databaseStorage Schema

localStorage Keys

bpl_settings_{uid}             → Settings JSON
bpl_profile_{uid}              → Profile JSON
bpl_sessions_{uid}             → Sessions Array JSON
bpl_last_uid                   → Last active UID string
BrainyPlayLab_progression_v2       → Progression v3 state
BrainyPlayLab_progression_baseline_rt → Baseline RT

Session Object

{
  id, timestamp, mode, level, roundsPlayed, durationSec,
  score, accuracy, correct, mistakes,
  medianRT, avgRT, consistency,
  streak, heartsLost, heartsRecovered,
  mistakes_selection, mistakes_timeout,
  cognitiveScores: { speed, attention, control, flexibility, overall },
  xpEarned
}

Progression v3 State

{
  totalCharge: 5000, neuralGrowthPoints: 45,
  chargeLevel: 8, growthStage: 12,
  chestProgress: 120, milestoneProgress: 500
}