Data Model & Database Schema

Relevant source files

The following files were used as context for generating this wiki page:

• convex/schema.ts
• convex/types.ts
• convex/_generated/dataModel.d.ts
• src/tests/store.test.ts
• convex/tests/rooms-and-games.test.ts
• convex/userPreferences.ts

The Dreamcats data model is designed to support a real-time, multiplayer card game environment using the Convex backend. It facilitates state synchronization across multiple players, persists user preferences, and tracks match history and statistics. The schema is built to handle both "online" and "hotseat" (local) game modes, ensuring that game state remains authoritative and protected against stale writes through versioning and idempotency keys.

The architecture relies on a centralized Convex database where the authoritative game state is stored in snapshots. Clients interact with this data via mutations and queries, while the frontend maintains a mirrored state using Zustand for reactive UI updates.

Sources: convex/schema.ts:1-125, src/tests/store.test.ts:7-40, README.md:1-20

Core Game Entities

The database schema defines several tables that manage the lifecycle of a game session, from room creation to match conclusion.

Rooms and Players

The rooms table acts as the primary container for a game session, identifying the host and current status. The players table links individual participants to these rooms, managing their connection status and seat assignments.

The rooms table supports indices for efficient lookups by roomId, hostId, and status. The players table tracks lastSeenAt to monitor presence.
Sources: convex/schema.ts:10-34, convex/tests/rooms-and-games.test.ts:81-118

Games and Moves

Authoritative game state is stored in the games table. Rather than normalization of every card, the state field holds an any type snapshot of the entire game logic state. To prevent race conditions, it uses a version field for optimistic concurrency control.

Field	Type	Description
roomId	string	Foreign key to the rooms table.
state	any	Authoritative snapshot of the game logic.
version	number	Monotonically increasing counter to avoid stale writes.
idempotencyKey	string	Prevents duplicate processing of the same action.

The moves table logs every discrete action taken by players, including a payload for move details and an idempotency key to ensure reliability in unstable network conditions.
Sources: convex/schema.ts:36-54, convex/tests/rooms-and-games.test.ts:40-70

User and Persistence Model

The system tracks user-specific data that persists across different game sessions, including authentication links and gameplay settings.

User Preferences and Stats

The userPreferences table stores client-side settings like theme and language, as well as pointers to active sessions for rejoin capabilities.

• Active Session Tracking: Stores activeRoomId, activePlayerId, and activeGameMode.
• Hotseat Recovery: The localGameState field allows users to resume local games after a refresh.
• User Stats: The userStats table aggregates performance metrics such as gamesPlayed, gamesWon, and bestScore.

Sources: convex/schema.ts:73-101, convex/userPreferences.ts:133-210

Match History

When a game concludes, data is archived into matches and matchPlayers tables for historical tracking.

Data Flow & Synchronization

The frontend synchronizes with the backend via a Zustand store that mirrors the Convex GameState.

State Synchronization Flow

The synchronization logic ensures that the UI reflects the authoritative backend state while handling local UI transitions.

Validation and Type Safety

The system uses Zod schemas in tests to validate the structure of the GameState. Key components of this state include:

• Draw/Discard Piles: Arrays of Card objects.
• Player Hands: Arrays of HandSlot objects (card + visibility flags).
• Game Phase: Enums like peeking, playing, round_end.

Sources: convex/tests/rooms-and-games.test.ts:10-70, src/types/index.ts:13-25

Conclusion

The Dreamcats data model provides a robust foundation for real-time multiplayer interactions. By utilizing Convex's reactive database and implementing optimistic concurrency through versioning, the system maintains a consistent "Dream" state across all clients while offering features like session recovery and detailed player statistics.