Skip to main content

Technical Decisions & Trade-offs

This document outlines the key technical decisions made during MindGames development and the reasoning behind them.

Architecture Decisions​

1. React Context vs Redux​

Decision: Use React Context with useReducer

Reasoning:

  • Application state is relatively simple (worksheet, answers, session)
  • No need for middleware or dev tools that Redux provides
  • Reduces bundle size and complexity
  • Sufficient for this single-page application

Trade-off:

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

2. Chain-Based Problem Generation​

Decision: Generate all chains upfront rather than 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-off:

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

3. Operation Mix Algorithm​

Decision: Weighted random selection with fallback strategies

// 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

Reasoning:

  • Respects user's preferred mix while ensuring chain generation succeeds
  • Handles edge cases (small maxResult, limited divisors)
  • Graceful degradation when optimal operation isn't possible

Trade-off:

  • Actual distribution may differ from configured percentages
  • More complex than simple random selection
  • Division-heavy mixes may not achieve exact percentages

4. Smart Starting Numbers for Multiply/Divide​

Decision: Use highly composite numbers (12, 24, 36, 60, etc.) when multiply/divide ≥50%

Reasoning:

  • Numbers like 24 and 60 have many divisors
  • Increases success rate for division operations
  • Produces more interesting multiplication chains
  • Reduces fallback to add/subtract

Trade-off:

  • Starting numbers are predictable in multiply/divide heavy modes
  • May produce patterns users recognize
  • Less variety in starting points

5. Tab Navigation Flow​

Decision: Tab submits answer AND moves to next input

Reasoning:

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

Trade-off:

  • Can't tab without submitting (must click elsewhere)
  • Accidental tab submits partial answers
  • Different from traditional quiz behavior

UI/UX Decisions​

6. Expand/Collapse Chain UI​

Decision: Active chain expanded, inactive chains collapsed

Reasoning:

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

Trade-off:

  • Can't work on multiple chains simultaneously
  • Transition animation adds latency
  • Less visible problem context

7. Kid Mode Celebrations​

Decision: 3-second confetti burst on completion

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)
  • Adds canvas-confetti dependency
  • Brief performance impact during animation

8. Wide Desktop Layout (1600px)​

Decision: Expand from typical 1200px max-width

Reasoning:

  • Math chains can be long horizontally
  • Modern monitors are wider
  • Settings sidebar doesn't compete for space
  • Better use of available screen real estate

Trade-off:

  • May feel sparse on ultra-wide monitors
  • Breaks conventional centered layout patterns
  • More horizontal eye movement

Technical Implementation Details​

9. Division Validation​

Decision: Only allow clean divisions (integer results)

if (operation === 'divide' && !Number.isInteger(result)) {
  return null;
}

Reasoning:

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

Trade-off:

  • Limits available division problems
  • May repeat similar divisor patterns
  • Not suitable for decimal practice

10. Minimum 10% Per Operation​

Decision: Enforce minimum 10% for each operation in mix

Reasoning:

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

Trade-off:

  • Can't do pure addition or multiplication practice
  • Limits customization freedom
  • May frustrate users wanting specific focus

Future Considerations​

Potential Improvements​

  1. Local Storage Persistence - Save settings and stats across sessions
  2. Difficulty Levels - Pre-configured difficulty presets
  3. Streak Tracking - Daily practice streak with rewards
  4. Sound Effects - Audio feedback for correct/incorrect
  5. Keyboard Shortcuts - Full keyboard navigation
  6. Print Mode - Generate printable worksheets

Known Limitations​

  • No offline support (could add PWA)
  • No user accounts (client-only)
  • No problem history (memory only)
  • Limited accessibility features