Technical documentation

Client & identity

• No accounts. The browser stores a random UUID in localStorage (cc_session_id). That value is sent as sessionId to identify the player in a room.
• UI language is chosen per device (cookie + React context); game card language is a per-room setting chosen by the host.

Backend (Convex)

• Mutations & queries in convex/rooms.ts: create room, join, leave, start game, play cards, judge round, close room, snapshots for the UI, idle tombstone lookup.
• convex/deck.ts: action to read uploaded custom deck JSON from storage and commit it to the room.
• convex/cardsData.ts: parses bundled JSON decks, validates custom JSON, builds card id → text maps.
• convex/crons.ts: periodic sweep of inactive open rooms.

Data model

• rooms — room code, host session id, game locale, intensity (1–3), open/closed, phase (lobby / submit / judge), Card Bro, draw & discard piles (card ids), submissions for the round, optional custom deck blob + cached JSON, activity timestamp.
• players — roomId, sessionId, display name, hand (white card ids), score, seat order.
• roomDepartures — short-lived tombstone after a room is hard-deleted for inactivity, so the client can show a specific message; keyed by room code, cleaned up after roughly 24 hours.

Game flow

1. Host creates a room; they are the first player and initial Card Bro.
2. Others join in lobby (max 12). Host starts — hands are dealt from the white draw pile.
3. Each round: one black card, non-Bro players submit one white each, Bro picks a winner, round finishes, hands refill, Bro rotates.
4. Bro may close the room; if everyone leaves, the room is marked closed. Open rooms with no activity for 30 minutes are deleted by cron (players removed, optional custom deck file deleted).

Built-in & custom decks

• Bundled decks live under convex/data/cards.*.json with tiers "1"–"3".
• Custom mode: host uploads JSON of the same shape; they declare exact black/white counts for the active tier; server validates structure, counts, and unique ids. No placeholder white cards are injected.

Room lifecycle & retention

Player rows are removed when they leave, when the Card Bro closes the room (the room document is deleted after a short tombstone is written), or when a room is purged for inactivity. Custom deck files in Convex storage are deleted when the room is removed or the file is replaced. See the Privacy Policy for retention details.