soroban-abacus-flashcards/.claude/terminology.md

Soroban Abacus Flashcards - Terminology Reference

User vs Player vs Room Member

CRITICAL: Do not confuse these three concepts!

Quick Reference

• USER = Identity/account (one per person, identified by guestId cookie)
• PLAYER = Game avatar/profile (multiple per user, from players table)
• ROOM MEMBER = USER's participation in a multiplayer room

Key Rule

When a USER joins a room, their ACTIVE PLAYERS join the game.

Example:

• USER "Jane" has 3 players: Alice, Bob, Charlie
• Alice and Bob are active (isActive: true)
• When Jane joins a room, Alice and Bob participate in the game
• The arcade_sessions.activePlayers array contains [alice_id, bob_id]

Database Schema

users (identity)
  ├─ players (avatars/profiles) - where isActive = true
  └─ room_members (room participation)

arcade_sessions
  ├─ userId: references users.id
  ├─ activePlayers: Array<player.id> ← PLAYER IDs, not USER IDs!
  └─ roomId: references arcade_rooms.id

Common Mistakes to Avoid

❌ Using USER ID in activePlayers - should be PLAYER IDs ❌ Assuming one USER = one PLAYER - users can have multiple players ❌ Tracking game moves/scores by USER - should track by PLAYER ❌ Confusing room_members.displayName with players.name - different concepts

Full Documentation

See: docs/terminology-user-player-room.md for complete explanation with examples.

Other Project-Specific Terms

Arcade vs Games

• /games/* - Single player or local multiplayer (same device)
• /arcade/* - Online multiplayer with sessions and rooms

Session Types

• Solo Session: arcade_sessions.roomId = null, user playing alone
• Room Session: arcade_sessions.roomId = room_xyz, shared game state across room members