Architecture & Technical Decisions

This document outlines the architecture, key technical decisions, and design trade-offs made during MindGames development.

System Architecture

MindGames follows a clean separation between UI components, state management, and business logic:

┌─────────────────────────────────────────────────────────────────┐
│                         UI Layer                                 │
│  ┌───────────────┐  ┌────────────────┐  ┌─────────────────┐    │
│  │  ChainDisplay │  │OperationSlider │  │     Timer       │    │
│  └───────────────┘  └────────────────┘  └─────────────────┘    │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                     State Management                             │
│  ┌─────────────────────────┐  ┌─────────────────────────┐      │
│  │      GameContext        │  │     ThemeContext        │      │
│  │  - worksheet            │  │  - theme (light/dark)   │      │
│  │  - answers              │  │  - profile (kid/adult)  │      │
│  │  - session              │  │                         │      │
│  │  - configuration        │  │                         │      │
│  └─────────────────────────┘  └─────────────────────────┘      │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                     Business Logic                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                 problem-generator.ts                      │   │
│  │  - generateChain()     - selectOperationByMix()          │   │
│  │  - generateWorksheet() - getSmartStartingNumber()        │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

State Management

Decision: React Context with useReducer

The application uses React Context with useReducer instead of external state libraries like Redux or Zustand.

Trade-offs:

• Less structured than Redux actions/reducers pattern
• No time-travel debugging
• Potential re-render issues with large state (mitigated with memoization)

Problem Generation Algorithm

Decision: Generate All Chains Upfront

When a user clicks "Generate," the entire worksheet (all chains and problems) is created at once rather than generating problems on-demand.

Reasoning:

• Allows progress tracking across entire worksheet
• Enables consistent session timing
• Simplifies state management (single source of truth)
• Better UX - no loading between chains

Trade-offs:

• Initial generation takes slightly longer
• All problems stored in memory
• Cannot dynamically adjust difficulty mid-session

Operation Mix Algorithm

The algorithm uses weighted random selection with fallback strategies to ensure chain generation always succeeds:

// Primary: Random selection based on percentages
const operation = selectOperationByMix(config.operationMix);

// Fallback 1: Try operations in order of percentage
const sortedOps = operations.sort((a, b) =>
  config.operationMix[b] - config.operationMix[a]
);

// Fallback 2: Simple add/subtract with small numbers
// Ensures chain generation never fails

This approach respects user preferences while handling edge cases like small maxResult values or limited divisors.

Smart Starting Numbers

When multiply/divide operations are 50% or more of the mix, the algorithm uses highly composite numbers (12, 24, 36, 60, etc.) as starting values.

Trade-off: Starting numbers become predictable in multiply/divide heavy modes, but this significantly improves generation success rate.

Division Validation

Decision: Only Allow Clean Divisions

Division operations only produce problems with integer results. Decimal results are rejected and alternative operations are attempted.

if (operation === 'divide' && !Number.isInteger(result)) {
  return null; // Reject and try another operation
}

Reasoning:

• Mental math with decimals is significantly harder
• Keeps focus on core arithmetic skills
• Matches typical educational approach for mental math
• Avoids rounding confusion

Trade-off: Limits available division problems and may repeat similar divisor patterns. Not suitable for decimal practice.

UI/UX Decisions

Tab Navigation Flow

Pressing Tab submits the current answer AND moves focus to the next input field.

Reasoning:

• Matches user expectation from form behavior
• Single keypress for the most common action
• Enter also works for those who prefer it
• Reduces friction in rapid-fire practice sessions

Trade-off: Cannot tab without submitting. Accidental tab submits partial answers.

Expand/Collapse Chain UI

The active chain is expanded while inactive chains are collapsed, showing only their completion status.

Reasoning:

• Focuses attention on the current problem
• Reduces cognitive overload
• Shows progress at a glance
• Allows many chains to fit on screen

Wide Desktop Layout (1600px)

The application expands to 1600px on large screens, wider than the typical 1200px max-width.

Reasoning:

• Math chains can be long horizontally
• Modern monitors are wider than traditional designs assume
• Settings sidebar does not compete for space with main content
• Better utilization of available screen real estate

Configuration Constraints

Minimum 10% Per Operation

Each operation type must have at least 10% allocation in the operation mix. Users cannot set an operation to 0%.

Reasoning:

• Ensures variety in every session
• Prevents single-operation monotony
• Balanced skill development
• Avoids edge cases with 0% operations

Trade-off: Cannot practice pure addition or multiplication. Limits customization for users wanting specific focus areas.

Kid Mode Celebrations

When Kid Mode is active and all chains are completed, a 3-second confetti burst animates on screen using the canvas-confetti library.

Reasoning:

• Provides dopamine hit for positive reinforcement
• Makes math practice feel rewarding
• Clear session boundary marker
• Appeals to younger users

Trade-off: May distract focused users (hence Adult mode exists). Adds canvas-confetti dependency. Brief performance impact during animation.

Known Limitations

Next Steps