soroban-abacus-flashcards/apps/web/.claude/GAME_SETTINGS_REFACTORING.md

Game Settings Persistence - Refactoring Recommendations

Current Pain Points

1. Type safety is weak - Easy to forget to add a setting in one place
2. Duplication - Config reading logic duplicated in socket-server.ts for each game
3. Manual synchronization - Have to manually keep validator signature, provider, and socket server in sync
4. Error-prone - Easy to hardcode values or forget to read from config

Recommended Refactorings

1. Create Shared Config Types (HIGHEST PRIORITY)

Problem: Each game's settings are defined in multiple places with no type enforcement

Solution: Define a single source of truth for each game's config

// src/lib/arcade/game-configs.ts

export interface MatchingGameConfig {
  gameType: 'abacus-numeral' | 'complement-pairs'
  difficulty: number
  turnTimer: number
}

export interface MemoryQuizGameConfig {
  selectedCount: 2 | 5 | 8 | 12 | 15
  displayTime: number
  selectedDifficulty: DifficultyLevel
  playMode: 'cooperative' | 'competitive'
}

export interface ComplementRaceGameConfig {
  // ... future settings
}

export interface RoomGameConfig {
  matching?: MatchingGameConfig
  'memory-quiz'?: MemoryQuizGameConfig
  'complement-race'?: ComplementRaceGameConfig
}

// Default configs
export const DEFAULT_MATCHING_CONFIG: MatchingGameConfig = {
  gameType: 'abacus-numeral',
  difficulty: 6,
  turnTimer: 30,
}

export const DEFAULT_MEMORY_QUIZ_CONFIG: MemoryQuizGameConfig = {
  selectedCount: 5,
  displayTime: 2.0,
  selectedDifficulty: 'easy',
  playMode: 'cooperative',
}

Benefits:

• Single source of truth for each game's settings
• TypeScript enforces consistency across codebase
• Easy to see what settings each game has

2. Create Config Helper Functions

Problem: Config reading logic is duplicated and error-prone

Solution: Centralized helper functions with type safety

// src/lib/arcade/game-config-helpers.ts

import type { GameName } from './validation'
import type { RoomGameConfig, MatchingGameConfig, MemoryQuizGameConfig } from './game-configs'
import { DEFAULT_MATCHING_CONFIG, DEFAULT_MEMORY_QUIZ_CONFIG } from './game-configs'

/**
 * Get game-specific config from room's gameConfig with defaults
 */
export function getGameConfig<T extends GameName>(
  roomGameConfig: RoomGameConfig | null | undefined,
  gameName: T
): T extends 'matching'
  ? MatchingGameConfig
  : T extends 'memory-quiz'
  ? MemoryQuizGameConfig
  : never {

  if (!roomGameConfig) {
    return getDefaultGameConfig(gameName) as any
  }

  const savedConfig = roomGameConfig[gameName]
  if (!savedConfig) {
    return getDefaultGameConfig(gameName) as any
  }

  // Merge saved config with defaults to handle missing fields
  const defaults = getDefaultGameConfig(gameName)
  return { ...defaults, ...savedConfig } as any
}

function getDefaultGameConfig(gameName: GameName) {
  switch (gameName) {
    case 'matching':
      return DEFAULT_MATCHING_CONFIG
    case 'memory-quiz':
      return DEFAULT_MEMORY_QUIZ_CONFIG
    case 'complement-race':
      // return DEFAULT_COMPLEMENT_RACE_CONFIG
      throw new Error('complement-race config not implemented')
    default:
      throw new Error(`Unknown game: ${gameName}`)
  }
}

/**
 * Update a specific game's config in the room's gameConfig
 */
export function updateGameConfig<T extends GameName>(
  currentRoomConfig: RoomGameConfig | null | undefined,
  gameName: T,
  updates: Partial<T extends 'matching' ? MatchingGameConfig : T extends 'memory-quiz' ? MemoryQuizGameConfig : never>
): RoomGameConfig {
  const current = currentRoomConfig || {}
  const gameConfig = current[gameName] || getDefaultGameConfig(gameName)

  return {
    ...current,
    [gameName]: {
      ...gameConfig,
      ...updates,
    },
  }
}

Usage in socket-server.ts:

// BEFORE (error-prone, duplicated)
const memoryQuizConfig = (room.gameConfig as any)?.['memory-quiz'] || {}
initialState = validator.getInitialState({
  selectedCount: memoryQuizConfig.selectedCount || 5,
  displayTime: memoryQuizConfig.displayTime || 2.0,
  selectedDifficulty: memoryQuizConfig.selectedDifficulty || 'easy',
  playMode: memoryQuizConfig.playMode || 'cooperative',
})

// AFTER (type-safe, concise)
const config = getGameConfig(room.gameConfig, 'memory-quiz')
initialState = validator.getInitialState(config)

Usage in RoomMemoryQuizProvider.tsx:

// BEFORE (verbose, error-prone)
const mergedInitialState = useMemo(() => {
  const gameConfig = roomData?.gameConfig as Record<string, any>
  const savedConfig = gameConfig?.['memory-quiz']

  return {
    ...initialState,
    selectedCount: savedConfig?.selectedCount ?? initialState.selectedCount,
    displayTime: savedConfig?.displayTime ?? initialState.displayTime,
    selectedDifficulty: savedConfig?.selectedDifficulty ?? initialState.selectedDifficulty,
    playMode: savedConfig?.playMode ?? initialState.playMode,
  }
}, [roomData?.gameConfig])

// AFTER (type-safe, concise)
const mergedInitialState = useMemo(() => {
  const config = getGameConfig(roomData?.gameConfig, 'memory-quiz')
  return {
    ...initialState,
    ...config,  // Spread config directly - all settings included
  }
}, [roomData?.gameConfig])

Benefits:

• No more manual property-by-property merging
• Type-safe
• Defaults handled automatically
• Reusable across codebase

3. Enforce Validator Config Type from Game Config

Problem: Easy to forget to add a new setting to validator's getInitialState() signature

Solution: Make validator use the shared config type

// src/lib/arcade/validation/MemoryQuizGameValidator.ts

import type { MemoryQuizGameConfig } from '@/lib/arcade/game-configs'

export class MemoryQuizGameValidator {
  // BEFORE: Manual type definition
  // getInitialState(config: {
  //   selectedCount: number
  //   displayTime: number
  //   selectedDifficulty: DifficultyLevel
  //   playMode?: 'cooperative' | 'competitive'
  // }): SorobanQuizState

  // AFTER: Use shared type
  getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
    return {
      // ...
      selectedCount: config.selectedCount,
      displayTime: config.displayTime,
      selectedDifficulty: config.selectedDifficulty,
      playMode: config.playMode,  // TypeScript ensures all fields are handled
      // ...
    }
  }
}

Benefits:

• If you add a setting to MemoryQuizGameConfig, TypeScript forces you to handle it
• Impossible to forget a setting
• Impossible to use wrong type

4. Add Exhaustiveness Checking

Problem: Easy to miss handling a setting field

Solution: Use TypeScript's exhaustiveness checking

// src/lib/arcade/validation/MemoryQuizGameValidator.ts

getInitialState(config: MemoryQuizGameConfig): SorobanQuizState {
  // Exhaustiveness check - ensures all config fields are used
  const _exhaustivenessCheck: Record<keyof MemoryQuizGameConfig, boolean> = {
    selectedCount: true,
    displayTime: true,
    selectedDifficulty: true,
    playMode: true,
  }

  return {
    // ... use all config fields
    selectedCount: config.selectedCount,
    displayTime: config.displayTime,
    selectedDifficulty: config.selectedDifficulty,
    playMode: config.playMode,
  }
}

If you add a new field to MemoryQuizGameConfig, TypeScript will error on _exhaustivenessCheck until you add it.

5. Validate Config on Save

Problem: Invalid config can be saved to database

Solution: Add runtime validation

// src/lib/arcade/game-config-helpers.ts

export function validateGameConfig(
  gameName: GameName,
  config: any
): config is MatchingGameConfig | MemoryQuizGameConfig {
  switch (gameName) {
    case 'matching':
      return (
        typeof config.gameType === 'string' &&
        ['abacus-numeral', 'complement-pairs'].includes(config.gameType) &&
        typeof config.difficulty === 'number' &&
        config.difficulty > 0 &&
        typeof config.turnTimer === 'number' &&
        config.turnTimer > 0
      )

    case 'memory-quiz':
      return (
        [2, 5, 8, 12, 15].includes(config.selectedCount) &&
        typeof config.displayTime === 'number' &&
        config.displayTime > 0 &&
        ['beginner', 'easy', 'medium', 'hard', 'expert'].includes(config.selectedDifficulty) &&
        ['cooperative', 'competitive'].includes(config.playMode)
      )

    default:
      return false
  }
}

Use in settings API:

// src/app/api/arcade/rooms/[roomId]/settings/route.ts

if (body.gameConfig !== undefined) {
  if (!validateGameConfig(room.gameName, body.gameConfig[room.gameName])) {
    return NextResponse.json({ error: 'Invalid game config' }, { status: 400 })
  }
  updateData.gameConfig = body.gameConfig
}

Schema Refactoring: Separate Table for Game Configs

Current Problem

All game configs are stored in a single JSON column in arcade_rooms.gameConfig:

{
  "matching": { "gameType": "...", "difficulty": 15 },
  "memory-quiz": { "selectedCount": 8, "playMode": "competitive" }
}

Issues:

• No schema validation
• Inefficient updates (read/parse/modify/serialize entire blob)
• Grows without bounds as more games added
• Can't query or index individual game settings
• No audit trail
• Potential concurrent update race conditions

Recommended: Separate Table

Create room_game_configs table with one row per game per room:

// src/db/schema/room-game-configs.ts

export const roomGameConfigs = sqliteTable('room_game_configs', {
  id: text('id').primaryKey().$defaultFn(() => createId()),
  roomId: text('room_id')
    .notNull()
    .references(() => arcadeRooms.id, { onDelete: 'cascade' }),
  gameName: text('game_name', {
    enum: ['matching', 'memory-quiz', 'complement-race'],
  }).notNull(),
  config: text('config', { mode: 'json' }).notNull(), // Game-specific JSON
  createdAt: integer('created_at', { mode: 'timestamp' })
    .notNull()
    .$defaultFn(() => new Date()),
  updatedAt: integer('updated_at', { mode: 'timestamp' })
    .notNull()
    .$defaultFn(() => new Date()),
}, (table) => ({
  uniqueRoomGame: uniqueIndex('room_game_idx').on(table.roomId, table.gameName),
}))

Benefits:

• ✅ Smaller rows (only configs for games that have been used)
• ✅ Easier updates (single row, not entire JSON blob)
• ✅ Can track updatedAt per game
• ✅ Better concurrency (no lock contention between games)
• ✅ Foundation for future audit trail

Migration Strategy:

1. Create new table
2. Migrate existing data from arcade_rooms.gameConfig
3. Update all config read/write code
4. Deploy and test
5. Drop old gameConfig column from arcade_rooms

See migration SQL below.

Implementation Priority

Phase 1: Schema Migration (HIGHEST PRIORITY)

1. Create new table - Add room_game_configs schema
2. Create migration - SQL to migrate existing data
3. Update helper functions - Adapt to new table structure
4. Update all read/write code - Use new table
5. Test thoroughly - Verify all settings persist correctly
6. Drop old column - Remove gameConfig from arcade_rooms

Phase 2: Type Safety (HIGH)

1. Create shared config types (game-configs.ts) - Prevents type mismatches
2. Create helper functions (game-config-helpers.ts) - Now queries new table
3. Update validators to use shared types - Enforces consistency

Phase 3: Compile-Time Safety (MEDIUM)

1. Add exhaustiveness checking - Catches missing fields at compile time
2. Enforce validator config types - Use shared types

Phase 4: Runtime Safety (LOW)

1. Add runtime validation - Prevents invalid data from being saved

Detailed Migration SQL

-- drizzle/migrations/XXXX_split_game_configs.sql

-- Create new table
CREATE TABLE room_game_configs (
  id TEXT PRIMARY KEY,
  room_id TEXT NOT NULL REFERENCES arcade_rooms(id) ON DELETE CASCADE,
  game_name TEXT NOT NULL CHECK(game_name IN ('matching', 'memory-quiz', 'complement-race')),
  config TEXT NOT NULL,  -- JSON
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

CREATE UNIQUE INDEX room_game_idx ON room_game_configs(room_id, game_name);

-- Migrate existing 'matching' configs
INSERT INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
SELECT
  lower(hex(randomblob(16))),
  id,
  'matching',
  json_extract(game_config, '$.matching'),
  created_at,
  last_activity
FROM arcade_rooms
WHERE json_extract(game_config, '$.matching') IS NOT NULL;

-- Migrate existing 'memory-quiz' configs
INSERT INTO room_game_configs (id, room_id, game_name, config, created_at, updated_at)
SELECT
  lower(hex(randomblob(16))),
  id,
  'memory-quiz',
  json_extract(game_config, '$."memory-quiz"'),
  created_at,
  last_activity
FROM arcade_rooms
WHERE json_extract(game_config, '$."memory-quiz"') IS NOT NULL;

-- After testing and verifying all works:
-- ALTER TABLE arcade_rooms DROP COLUMN game_config;

Migration Strategy

Step-by-Step with Checkpoints

Checkpoint 1: Schema & Migration

1. Create src/db/schema/room-game-configs.ts
2. Export from src/db/schema/index.ts
3. Generate and apply migration
4. Verify data migrated correctly

Checkpoint 2: Helper Functions

1. Create shared config types in src/lib/arcade/game-configs.ts
2. Create helper functions in src/lib/arcade/game-config-helpers.ts
3. Add unit tests for helpers

Checkpoint 3: Update Config Reads

1. Update socket-server.ts to read from new table
2. Update RoomMemoryQuizProvider to read from new table
3. Update RoomMemoryPairsProvider to read from new table
4. Test: Load room and verify settings appear

Checkpoint 4: Update Config Writes

1. Update useRoomData.ts updateGameConfig to write to new table
2. Update settings API to write to new table
3. Test: Change settings and verify they persist

Checkpoint 5: Update Validators

1. Update validators to use shared config types
2. Test: All games work correctly

Checkpoint 6: Cleanup

1. Remove old gameConfig column references
2. Drop gameConfig column from arcade_rooms table
3. Final testing of all games

Benefits Summary

• Type Safety: TypeScript enforces consistency across all systems
• DRY: Config reading logic not duplicated
• Maintainability: Adding a setting requires changes in fewer places
• Correctness: Impossible to forget a setting or use wrong type
• Debugging: Centralized config logic easier to trace
• Testing: Can test config helpers in isolation