Data Models (Types)
Relevant source files
The following files were used as context for generating this wiki page:
This document outlines the core data structures and TypeScript types that form the backbone of the "Hold-em or Fold-em Poker" application. These models define the shape of data for game state, player information, tournaments, and other related features, ensuring type safety and a consistent data flow across the application, from the poker engine logic to the React components.
The primary types are defined in the /types directory and are consumed by various parts of the application, including the game logic in lib/poker-engine.ts, state management hooks like hooks/use-poker-game.tsx, and UI components.
Core Poker Game Models
These models are central to the poker gameplay itself, managing everything from the cards in a player's hand to the overall state of a game session.
Sources: types/poker.ts, lib/poker-engine.ts
Entity Relationship Diagram
The following diagram illustrates the relationships between the main entities of the poker game.
Generating architecture diagram...
Sources: types/poker.ts:29-59
GameState
The GameState interface is the most critical data structure, representing the complete state of a single poker hand at any given moment.
| Field | Type | Description | Source |
|---|---|---|---|
phase | GamePhase | The current betting round or phase of the hand. | [types/poker.ts:49](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L49) |
pot | number | The total amount of chips in the main pot. | [types/poker.ts:50](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L50) |
sidePots | SidePot[] | An array of side pots created when players go all-in. | [types/poker.ts:51](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L51) |
communityCards | Card[] | The face-up community cards on the table. | [types/poker.ts:52](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L52) |
currentBet | number | The highest bet amount that players must match. | [types/poker.ts:53](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L53) |
currentPlayerIndex | number | The index of the player whose turn it is to act. | [types/poker.ts:54](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L54) |
dealerIndex | number | The index of the player with the dealer button. | [types/poker.ts:55](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L55) |
dealerSeatNumber | number | The seat number of the player with the dealer button. | [types/poker.ts:56](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L56) |
smallBlindIndex | number | The index of the player in the small blind position. | [types/poker.ts:57](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L57) |
bigBlindIndex | number | The index of the player in the big blind position. | [types/poker.ts:58](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L58) |
players | PlayerState[] | An array of objects representing each player in the hand. | [types/poker.ts:59](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L59) |
winners | string[] | An array of player IDs who won the hand. | [types/poker.ts:61](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L61) |
handNumber | number | A counter for the number of hands played. | [types/poker.ts:62](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L62) |
gameMode | GameMode | The variant of poker being played (e.g., 'sng', 'omaha'). | [types/poker.ts:63](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L63) |
PlayerState
This interface holds all the information relevant to a single player within a hand.
| Field | Type | Description | Source |
|---|---|---|---|
id | string | The unique identifier for the player. | [types/poker.ts:30](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L30) |
name | string | The player's display name. | [types/poker.ts:31](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L31) |
chips | number | The player's current chip stack. | [types/poker.ts:32](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L32) |
bet | number | The amount the player has bet in the current round. | [types/poker.ts:33](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L33) |
cards | Card[] | The player's private hole cards. | [types/poker.ts:34](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L34) |
folded | boolean | true if the player has folded their hand. | [types/poker.ts:35](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L35) |
allIn | boolean | true if the player has bet all their chips. | [types/poker.ts:36](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L36) |
isActive | boolean | true if the player is still active in the game/tournament. | [types/poker.ts:37](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L37) |
lastAction | PlayerAction | The last action taken by the player. | [types/poker.ts:38](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L38) |
seatNumber | number | The player's seat number at the table. | [types/poker.ts:39](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L39) |
Card, Suit, and Rank
These fundamental types define a playing card.
export type Suit = "hearts" | "diamonds" | "clubs" | "spades"
export type Rank = "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "J" | "Q" | "K" | "A"
export interface Card {
suit: Suit
rank: Rank
}
Sources: types/poker.ts:1-7
Enumerated Types
Several type aliases are used to represent distinct sets of states or actions within the game.
| Type Name | Possible Values | Description | Source |
|---|---|---|---|
GamePhase | waiting, pre-flop, flop, turn, river, showdown, complete | Represents the different stages of a hand. | [types/poker.ts:27](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L27) |
PlayerAction | fold, check, call, raise, all-in | Represents the possible actions a player can take. | [types/poker.ts:26](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L26) |
GameMode | sng, mtt, allin, omaha | Defines the poker variant being played. | [types/poker.ts:28](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L28) |
HandRank | royal-flush, straight-flush, four-of-a-kind, etc. | The standard poker hand rankings. | [types/poker.ts:10-20](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/types/poker.ts#L10-L20) |
Game Phase Flow
The GamePhase progresses in a set sequence, managed by the advancePhase function in the poker engine.
Generating architecture diagram...
This flow is derived from the logic in lib/poker-engine.ts:550-580.
Tournament Models
These types are used to manage the structure and state of multi-table (MTT) and sit-and-go (SNG) tournaments.
Sources: components/tournament-structure.tsx, components/tournament-table-info.tsx
Tournament Relationship Diagram
Generating architecture diagram...
This diagram is an interpretation of the props and state used in components/tournament-table-info.tsx and components/tournament-structure.tsx.
Tournament
This model represents the high-level state of an ongoing tournament. Its structure is inferred from the useTournament hook as consumed by TournamentTableInfo.
| Field | Type | Description | Source |
|---|---|---|---|
config | TournamentConfig | The static configuration of the tournament. | [components/tournament-table-info.tsx:9](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-table-info.tsx#L9) |
phase | string | The current phase of the tournament (e.g., 'running'). | [components/tournament-table-info.tsx:13](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-table-info.tsx#L13) |
remainingPlayers | number | The number of players still in the tournament. | [components/tournament-table-info.tsx:80](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-table-info.tsx#L80) |
totalPlayers | number | The total number of players who entered. | [components/tournament-table-info.tsx:80](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-table-info.tsx#L80) |
totalPrizePool | number | The total prize pool to be distributed. | [components/tournament-table-info.tsx:91](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-table-info.tsx#L91) |
TournamentConfig & BlindLevel
The TournamentConfig defines the rules and structure for a tournament, including the blind schedule. This structure is inferred from the props of the TournamentStructure component.
TournamentConfig Properties
| Field | Type | Description | Source |
|---|---|---|---|
blindStructure | BlindLevel[] | An array defining each blind level. | [components/tournament-structure.tsx:10, 30](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L10) |
prizePoolPercentages | number[] | An array of percentages for prize distribution. | [components/tournament-structure.tsx:10, 80](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L10) |
BlindLevel Properties
| Field | Type | Description | Source |
|---|---|---|---|
level | number | The level number. | [components/tournament-structure.tsx:31](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L31) |
smallBlind | number | The small blind amount for this level. | [components/tournament-structure.tsx:47](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L47) |
bigBlind | number | The big blind amount for this level. | [components/tournament-structure.tsx:47](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L47) |
ante | number | The ante amount for this level. | [components/tournament-structure.tsx:49](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L49) |
duration | number | The duration of the level in seconds. | [components/tournament-structure.tsx:55](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/tournament-structure.tsx#L55) |
User Profile & Social Models
These data models define the structure for user profiles, including their stats, achievements, and social items like gifts. The structure is inferred from props passed to various page components.
Sources: components/user-profile.tsx, components/stats-dashboard.tsx, components/achievements-page.tsx, components/gifts-page.tsx
Profile Entity Relationship Diagram
This diagram shows how the main Profile object relates to its sub-models.
Generating architecture diagram...
This diagram is an interpretation of the profile prop used in components/user-profile.tsx and its related page components.
Profile
Inferred from the profile prop in UserProfileProps.
| Field | Type | Description | Source |
|---|---|---|---|
id | string | User's unique ID. | [components/user-profile.tsx:75](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L75) |
name | string | User's display name. | [components/user-profile.tsx:96](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L96) |
avatar | string | URL to the user's avatar image. | [components/user-profile.tsx:86](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L86) |
isVerified | boolean | Whether the user is a verified player. | [components/user-profile.tsx:98](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L98) |
chips | number | User's total chip count. | [components/user-profile.tsx:114](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L114) |
bio | string | User's personal biography. | [components/user-profile.tsx:159](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L159) |
stats | PlayerStats | Object containing the player's game statistics. | [components/user-profile.tsx:178](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L178) |
achievements | Achievement[] | Array of unlocked achievements. | [components/user-profile.tsx:195](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L195) |
bigFans | any[] | Array of users who are "big fans". | [components/user-profile.tsx:219](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L219) |
giftsReceived | Gift[] | Array of gifts the user has received. | [components/user-profile.tsx:244](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/user-profile.tsx#L244) |
PlayerStats
Inferred from the stats object in StatsDashboard.
| Field | Type | Description | Source |
|---|---|---|---|
totalHands | number | Total number of hands played. | [components/stats-dashboard.tsx:18](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L18) |
maxProfit | number | Maximum profit won in a single hand. | [components/stats-dashboard.tsx:19](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L19) |
winRate | number | Percentage of hands won. | [components/stats-dashboard.tsx:20](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L20) |
vpip | number | Voluntarily Put money In Pot percentage. | [components/stats-dashboard.tsx:21](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L21) |
pfr | number | Pre-Flop Raise percentage. | [components/stats-dashboard.tsx:22](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L22) |
wtsd | number | Went To ShowDown percentage. | [components/stats-dashboard.tsx:23](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L23) |
reRaiseRate | number | Percentage of time the player re-raises. | [components/stats-dashboard.tsx:24](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L24) |
cBetRate | number | Continuation Bet percentage. | [components/stats-dashboard.tsx:25](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L25) |
bestHand | object | An object describing the player's best hand. | [components/stats-dashboard.tsx:26](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/stats-dashboard.tsx#L26) |
Achievement & Gift
These models represent collectible items on a user's profile.
Achievement Properties (inferred from AchievementsPage)
| Field | Type | Description | Source |
|---|---|---|---|
id | string | Unique ID for the achievement. | [components/achievements-page.tsx:22](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L22) |
name | string | Name of the achievement. | [components/achievements-page.tsx:23](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L23) |
icon | string | Emoji or icon representing the achievement. | [components/achievements-page.tsx:24](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L24) |
description | string | How to unlock the achievement. | [components/achievements-page.tsx:25](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L25) |
rarity | string | Rarity level (e.g., 'common', 'legendary'). | [components/achievements-page.tsx:26](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L26) |
unlocked | boolean | Whether the player has unlocked it. | [components/achievements-page.tsx:27](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L27) |
category | string | Category of the achievement (e.g., 'wins'). | [components/achievements-page.tsx:30](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/achievements-page.tsx#L30) |
Gift Properties (inferred from GiftsPage)
| Field | Type | Description | Source |
|---|---|---|---|
id | string | Unique ID for the gift. | [components/gifts-page.tsx:20](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L20) |
icon | string | Emoji or icon representing the gift. | [components/gifts-page.tsx:21](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L21) |
name | string | Name of the gift. | [components/gifts-page.tsx:22](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L22) |
from | string | Name of the player who sent the gift. | [components/gifts-page.tsx:23](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L23) |
date | string | Date the gift was received. | [components/gifts-page.tsx:24](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L24) |
forSale | boolean | Whether the gift is listed for sale by the owner. | [components/gifts-page.tsx:25](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L25) |
category | string | Category of the gift (e.g., 'fun', 'luxury'). | [components/gifts-page.tsx:26](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/gifts-page.tsx#L26) |
Supporting Models
StakeTable
This interface, defined in TableSelection, describes a single cash game or tournament table that a player can join.
| Field | Type | Description | Source |
|---|---|---|---|
id | string | Unique identifier for the table. | [components/table-selection.tsx:11](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L11) |
name | string | The display name of the table. | [components/table-selection.tsx:12](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L12) |
smallBlind | number | The small blind amount. | [components/table-selection.tsx:13](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L13) |
bigBlind | number | The big blind amount. | [components/table-selection.tsx:14](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L14) |
minBuyIn | number | The minimum chips required to join. | [components/table-selection.tsx:15](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L15) |
maxBuyIn | number | The maximum chips a player can bring to the table. | [components/table-selection.tsx:16](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L16) |
currentPlayers | number | The number of players currently at the table. | [components/table-selection.tsx:17](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L17) |
maxPlayers | number | The maximum capacity of the table. | [components/table-selection.tsx:18](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L18) |
isVip | boolean | Whether the table is for VIP players only. | [components/table-selection.tsx:19](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L19) |
difficulty | 'Beginner' | 'Intermediate' | 'Advanced' | 'Expert' | The skill level rating for the table. | [components/table-selection.tsx:20](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L20) |
gameMode | GameMode | The poker variant played at this table. | [components/table-selection.tsx:21](https://github.com/amvicioushecs/Hold-em-or-Fold-em-Poker/blob/HEAD/components/table-selection.tsx#L21) |