Provably fair, single-table Texas Hold'em with on-chain custody and commitments.

flowchart TB
  Wallet["Player wallet"]
  subgraph Browser["Browser - packages/client"]
    UI["React pages / wallet controls"]
    Hook["useGame socket controller"]
    BV["Browser verifier"]
  end
  subgraph Server["Node server - packages/server"]
    Entry["index.ts + Socket.IO auth"]
    Room["Room hand loop"]
    Engine["betting.ts + pot.ts"]
    API["Express read API"]
    Chain["EthersChainService"]
    DB["Store / SQLite"]
  end
  Protocol["@uholdem/protocol"]
  subgraph EVM["Ethereum Sepolia or Anvil"]
    Token["MockUSDC"]
    Vault["ChipVault"]
    Table["PokerTable"]
  end
  Wallet -->|"sign messages and transactions"| UI
  UI --> Hook
  Hook <-->|"Socket.IO"| Entry
  Entry --> Room
  Room --> Engine
  Room --> Protocol
  Room --> DB
  Room --> Chain
  UI -->|"HTTP config / records"| API
  API --> DB
  API --> Chain
  BV --> Protocol
  BV -->|"read roots via /api/rpc"| Table
  Chain -->|"operator writes / reads"| Table
  UI -->|"player writes"| Token
  UI --> Vault
  UI --> Table
  Table --> Vault
  Vault --> Token

sequenceDiagram
  autonumber
  actor W as Wallet
  participant C as React client
  participant S as Server Room
  participant P as Protocol
  participant T as PokerTable
  participant D as SQLite
  W->>C: connect
  C->>S: auth request / signed nonce
  S-->>C: memory session token
  S->>T: seats and open-hand check
  S->>P: buildEpoch
  S->>T: commitEpoch and wait
  S-->>C: entropy typed data
  W->>C: signTypedData
  C->>S: entropy:sign
  S->>P: buildEntropy then dealHand
  P-->>S: layout + two roots
  S->>T: startHand and wait
  S->>T: reread handRoots
  S->>D: persist deal metadata
  S-->>C: private hole opening
  C->>T: independently read dealRoot
  C->>P: verifyReveal
  loop Betting streets
    S-->>C: legal actions + deadline
    C->>S: action
    S->>S: applyAction and persist
    S-->>C: street opening
    C->>P: verifyReveal
  end
  S->>P: rank and award pots
  S->>D: finishHand exact settlement
  S->>T: settleHand
  S-->>C: result immediately
  T-->>S: receipt and sync seats
  C->>D: fetch delayed hand record
  C->>T: read roots independently
  C->>P: verifyHand

stateDiagram-v2
  [*] --> waiting
  waiting --> paused: epoch commit or recovery
  paused --> waiting: retry or abort succeeds
  waiting --> collecting_entropy: 2+ eligible seats
  collecting_entropy --> waiting: fewer than 2 signatures
  collecting_entropy --> committing: valid signatures
  committing --> betting: start confirmed + root reread
  betting --> betting: action or street
  betting --> showdown: one live player or river
  showdown --> settling: awards computed
  settling --> waiting: result emitted
  settling --> paused: settlement failure

erDiagram
  EPOCHS ||--o{ HANDS : contains
  HANDS ||--|{ PLAYER_SIGNATURES : has
  HANDS ||--|{ COMMITMENTS : fixes
  HANDS ||--o{ REVEALS : opens
  HANDS ||--o{ HAND_ACTIONS : records
  HANDS ||--o{ PAYOUTS : settles