soroban-abacus-flashcards/apps/web/docs/AUDIT_MODULAR_GAME_SYSTEM.md

Modular Game System Audit

Date: 2025-10-15 Updated: 2025-10-15 Status: ✅ CRITICAL ISSUE RESOLVED

---

Executive Summary

The modular game system now meets its stated intentions after implementing the unified validator registry. The critical dual registration issue has been resolved.

Original Issue: Client-side implementation (SDK, registry, game definitions) was well-designed, but server-side validation used a hard-coded legacy system, breaking the core premise of modularity.

Resolution: Created unified isomorphic validator registry (src/lib/arcade/validators.ts) that serves both client and server needs, with auto-derived GameName type.

Verdict: ✅ Production Ready - System is now truly modular with single registration point

---

Intention vs. Reality

Stated Intentions

"A modular, plugin-based architecture for building multiplayer arcade games"

Goals:

1. Modularity: Each game is self-contained and independently deployable
2. Games register themselves with a central registry
3. No need to modify core infrastructure when adding games

Current Reality

✅ Client-Side: Fully modular, games use SDK and register themselves ❌ Server-Side: Hard-coded validator map, requires manual code changes ❌ Overall: System is NOT modular - adding a game requires editing 2 different registries

---

Critical Issues

✅ Issue #1: Dual Registration System (RESOLVED)

Original Problem: Games had to register in TWO separate places:

1. Client Registry (src/lib/arcade/game-registry.ts)
2. Server Validator Map (src/lib/arcade/validation/index.ts)

Impact:

• ❌ Broke modularity - couldn't just drop in a new game
• ❌ Easy to forget one registration, causing runtime errors
• ❌ Violated DRY principle
• ❌ Two sources of truth for "what games exist"

Resolution (Implemented 2025-10-15):

Created unified isomorphic validator registry at src/lib/arcade/validators.ts:

export const validatorRegistry = {
  matching: matchingGameValidator,
  'memory-quiz': memoryQuizGameValidator,
  'number-guesser': numberGuesserValidator,
  // Add new games here - GameName type auto-updates!
} as const

// Auto-derived type - no manual updates needed!
export type GameName = keyof typeof validatorRegistry

Changes Made:

1. ✅ Created src/lib/arcade/validators.ts - Unified validator registry (isomorphic)
2. ✅ Updated validation/index.ts - Now re-exports from unified registry (backwards compatible)
3. ✅ Updated validation/types.ts - GameName now auto-derived (no more hard-coded union)
4. ✅ Updated session-manager.ts - Imports from unified registry
5. ✅ Updated socket-server.ts - Imports from unified registry
6. ✅ Updated route.ts - Uses hasValidator() instead of hard-coded array
7. ✅ Updated game-config-helpers.ts - Handles ExtendedGameName for legacy games
8. ✅ Updated game-registry.ts - Added runtime validation check

Benefits:

• ✅ Single registration point for validators
• ✅ Auto-derived GameName type (no manual updates)
• ✅ Type-safe validator access
• ✅ Backwards compatible with existing code
• ✅ Runtime warnings for registration mismatches

Commit: refactor(arcade): create unified validator registry to fix dual registration (9459f37b)

---

✅ Issue #2: Validators Not Accessible from Registry (RESOLVED)

Original Problem: The GameDefinition contained validators, but server couldn't access them because game-registry.ts imported React components.

Resolution: Created separate isomorphic validator registry that server can import without pulling in client-only code.

How It Works Now:

• src/lib/arcade/validators.ts - Isomorphic, server can import safely
• src/lib/arcade/game-registry.ts - Client-only, imports React components
• Both use the same validator instances (verified at runtime)

Benefits:

• ✅ Server has direct access to validators
• ✅ No need for dual validator maps
• ✅ Clear separation: validators (isomorphic) vs UI (client-only)

---

⚠️ Issue #3: Type System Fragmentation

Problem: Multiple overlapping type definitions for same concepts:

GameValidator has THREE definitions:

1. validation/types.ts - Legacy validator interface
2. game-sdk/types.ts - SDK validator interface (extends legacy)
3. Individual game validators - Implement one or both?

GameMove has TWO type systems:

1. validation/types.ts - Legacy move types (MatchingFlipCardMove, etc.)
2. Game-specific types in each game's types.ts

GameName is hard-coded:

// validation/types.ts:9
export type GameName = 'matching' | 'memory-quiz' | 'complement-race' | 'number-guesser'

This must be manually updated for every new game!

Impact:

• Confusing which types to use
• Easy to use wrong import
• GameName type doesn't auto-update from registry

---

⚠️ Issue #4: Old Games Not Migrated

Problem: Existing games (matching, memory-quiz) still use old structure:

Old Pattern (matching, memory-quiz):

src/app/arcade/matching/
  ├── context/           (Old pattern)
  │   └── RoomMemoryPairsProvider.tsx
  └── components/

New Pattern (number-guesser):

src/arcade-games/number-guesser/
  ├── index.ts           (New pattern)
  ├── Validator.ts
  ├── Provider.tsx
  └── components/

Impact:

• Inconsistent codebase structure
• Two different patterns developers must understand
• Documentation shows new pattern, but most games use old pattern
• Confusing for new developers

Evidence:

• src/app/arcade/matching/ - Uses old structure
• src/app/arcade/memory-quiz/ - Uses old structure
• src/arcade-games/number-guesser/ - Uses new structure

---

✅ Issue #5: Manual GameName Type Updates (RESOLVED)

Original Problem: GameName type was a hard-coded union that had to be manually updated for each new game.

Resolution: Changed validator registry from Map to const object, enabling type derivation:

// src/lib/arcade/validators.ts
export const validatorRegistry = {
  matching: matchingGameValidator,
  'memory-quiz': memoryQuizGameValidator,
  'number-guesser': numberGuesserValidator,
  // Add new games here...
} as const

// Auto-derived! No manual updates needed!
export type GameName = keyof typeof validatorRegistry

Benefits:

• ✅ GameName type updates automatically when adding to registry
• ✅ Impossible to forget type update (it's derived)
• ✅ Single registration step (just add to validatorRegistry)
• ✅ Type-safe throughout codebase

---

Secondary Issues

Issue #6: No Server-Side Registry Access

Problem: Server code cannot import game-registry.ts because it contains React components.

Why:

• GameDefinition includes Provider and GameComponent (React components)
• Server-side code runs in Node.js, can't import React components
• No way to access just the validator from registry

Potential Solutions:

1. Split registry into isomorphic and client-only parts
2. Separate validator registration from game registration
3. Use conditional exports in package.json

---

Issue #7: Documentation Doesn't Match Reality

Problem: Documentation describes a fully modular system, but reality requires manual edits in multiple places.

From README.md:

"Step 7: Register Game - Add to src/lib/arcade/game-registry.ts"

Missing Steps:

• Also add to validation/index.ts validator map
• Also add to GameName type union
• Import validator in server files

Impact: Developers follow docs, game doesn't work, confusion ensues.

---

Issue #8: No Validation of Registered Games

Problem: Registration is type-safe but has no runtime validation:

registerGame(numberGuesserGame)  // No validation that validator works

Missing Checks:

• Does validator implement all required methods?
• Does manifest match expected schema?
• Are all required fields present?
• Does validator.getInitialState() return valid state?

Impact: Bugs only caught at runtime when game is played.

---

Proposed Solutions

Solution 1: Unified Server-Side Registry (RECOMMENDED)

Create isomorphic validator registry:

// src/lib/arcade/validators.ts (NEW FILE - isomorphic)
import { numberGuesserValidator } from '@/arcade-games/number-guesser/Validator'
import { matchingGameValidator } from '@/lib/arcade/validation/MatchingGameValidator'
// ... other validators

export const validatorRegistry = new Map([
  ['number-guesser', numberGuesserValidator],
  ['matching', matchingGameValidator],
  // ...
])

export function getValidator(gameName: string) {
  const validator = validatorRegistry.get(gameName)
  if (!validator) throw new Error(`No validator for game: ${gameName}`)
  return validator
}

export type GameName = keyof typeof validatorRegistry  // Auto-derived!

Update game-registry.ts to use this:

// src/lib/arcade/game-registry.ts
import { getValidator } from './validators'

export function registerGame(game: GameDefinition) {
  const { name } = game.manifest

  // Verify validator is registered server-side
  const validator = getValidator(name)
  if (validator !== game.validator) {
    console.warn(`[Registry] Validator mismatch for ${name}`)
  }

  registry.set(name, game)
}

Pros:

• Single source of truth for validators
• Auto-derived GameName type
• Client and server use same validator
• Only one registration needed

Cons:

• Still requires manual import in validators.ts
• Doesn't solve "drop in a game" fully

---

Solution 2: Code Generation

Auto-generate validator registry from file system:

// scripts/generate-registry.ts
// Scans src/arcade-games/**/Validator.ts
// Generates validators.ts and game-registry imports

Pros:

• Truly modular - just add folder, run build
• No manual registration
• Auto-derived types

Cons:

• Build-time complexity
• Magic (harder to understand)
• May not work with all bundlers

---

Solution 3: Split GameDefinition

Separate client and server concerns:

// Isomorphic (client + server)
export interface GameValidatorDefinition {
  name: string
  validator: GameValidator
  defaultConfig: GameConfig
}

// Client-only
export interface GameUIDefinition {
  name: string
  manifest: GameManifest
  Provider: GameProviderComponent
  GameComponent: GameComponent
}

// Combined (client-only)
export interface GameDefinition extends GameValidatorDefinition, GameUIDefinition {}

Pros:

• Clear separation of concerns
• Server can import just validator definition
• Type-safe

Cons:

• More complexity
• Still requires two registries

---

Immediate Action Items

Critical (Do Before Next Game)

1. ✅ Document the dual registration requirement (COMPLETED)

   • ✅ Update README with both registration steps
   • ✅ Add troubleshooting section for "game not found" errors
   • ✅ Document unified validator registry in Step 7

2. ✅ Unify validator registration (COMPLETED 2025-10-15)

   • ✅ Chose Solution 1 (Unified Server-Side Registry)
   • ✅ Implemented unified registry (src/lib/arcade/validators.ts)
   • ✅ Updated session-manager.ts and socket-server.ts
   • ✅ Tested with number-guesser (no TypeScript errors)

3. ✅ Auto-derive GameName type (COMPLETED 2025-10-15)

   • ✅ Removed hard-coded union
   • ✅ Derive from validator registry using keyof typeof
   • ✅ Updated all usages (backwards compatible via re-exports)

High Priority

4. 🟡 Migrate old games to new pattern

   • Move matching to arcade-games/matching/
   • Move memory-quiz to arcade-games/memory-quiz/
   • Update imports and tests
   • OR document that old games use old pattern (transitional)

5. 🟡 Add validator registration validation

   • Runtime check in registerGame()
   • Warn if validator missing
   • Validate manifest schema

Medium Priority

6. 🟢 Clean up type definitions

   • Consolidate GameValidator types
   • Single source of truth for GameMove
   • Clear documentation on which to use

7. 🟢 Update documentation

   • Add "dual registry" warning
   • Update step-by-step guide
   • Add troubleshooting for common mistakes

---

Architectural Debt

Technical Debt Accumulated

1. Old validation system (validation/types.ts, validation/index.ts)

   • Used by server-side code
   • Hard-coded game list
   • No migration path documented

2. Mixed game structures (old in app/arcade/, new in arcade-games/)

   • Confusing for developers
   • Inconsistent imports
   • Harder to maintain

3. Type fragmentation (3 GameValidator definitions)

   • Unclear which to use
   • Potential for bugs
   • Harder to refactor

Migration Path

Option A: Big Bang (Risky)

• Migrate all games to new structure in one PR
• Update server to use unified registry
• High risk of breakage

Option B: Incremental (Safer)

• Document dual registration as "current reality"
• Create unified validator registry (doesn't break old games)
• Slowly migrate old games one by one
• Eventually deprecate old validation system

Recommendation: Option B (Incremental)

---

Compliance with Intentions

Intention	Status	Notes
Modularity	✅ Pass	Single registration in validators.ts + game-registry.ts
Self-registration	✅ Pass	Both client and server use unified registry
Type safety	✅ Pass	Good TypeScript coverage + auto-derived GameName
No core changes	⚠️ Improved	Must edit validators.ts, but one central file
Drop-in games	⚠️ Improved	Two registration points (validator + game def)
Stable SDK API	✅ Pass	SDK is well-designed and consistent
Clear patterns	⚠️ Partial	New pattern is clear, but old games don't follow it

Original Grade: D (Failed core modularity requirement) Current Grade: B+ (Modularity achieved, some legacy migration pending)

---

Positive Aspects (What Works Well)

1. ✅ SDK Design - Clean, well-documented, type-safe
2. ✅ Client-Side Registry - Simple, effective pattern
3. ✅ GameDefinition Structure - Good separation of concerns
4. ✅ Documentation - Comprehensive (though doesn't match reality)
5. ✅ defineGame() Helper - Makes game creation easy
6. ✅ Type Safety - Excellent TypeScript coverage
7. ✅ Number Guesser Example - Good reference implementation

---

Recommendations

Immediate (This Sprint)

1. ✅ Document current reality - Update docs to show both registrations required
2. 🔴 Create unified validator registry - Implement Solution 1
3. 🔴 Update server to use unified registry - Modify session-manager.ts and socket-server.ts

Next Sprint

4. 🟡 Migrate one old game - Move matching to new structure as proof of concept
5. 🟡 Add registration validation - Runtime checks for validator consistency
6. 🟡 Auto-derive GameName - Remove hard-coded type union

Future

7. 🟢 Code generation - Explore automated registry generation
8. 🟢 Plugin system - True drop-in games with discovery
9. 🟢 Deprecate old validation system - Once all games migrated

---

Conclusion

The modular game system has a solid foundation but is not truly modular due to server-side technical debt. The client-side implementation is excellent, but the server still uses a legacy hard-coded validation system.

Status: Needs significant refactoring before claiming "modular architecture"

Path Forward: Implement unified validator registry (Solution 1), then incrementally migrate old games.

Risk: If we add more games before fixing this, technical debt will compound.

---

This audit was conducted by reviewing:

• src/lib/arcade/game-registry.ts
• src/lib/arcade/validation/index.ts
• src/lib/arcade/session-manager.ts
• src/socket-server.ts
• src/lib/arcade/game-sdk/
• src/arcade-games/number-guesser/
• Documentation in docs/ and src/arcade-games/README.md