blackjack/docs/game_flowchart.md

# Game flowchart

```mermaid
flowchart TD
  A[Start: play_round()] --> B[Shuffle deck and deal cards]
  B --> C[Player gets 2 cards, Dealer gets 1 face-up, 1 face-down]
  C --> D{Dealer's face-up card is Ace or 10-value?}
  D -- Yes --> E{Does Dealer have Blackjack?}
  E -- Yes --> F[Dealer reveals face-down card]
  F --> G{Does Player also have Blackjack?}
  G -- Yes --> P[PUSH (Tie)]
  G -- No --> L[Player loses]
  D -- No --> H[Player turn loop]
  E -- No --> H
  H --> I{Player chooses Hit or Stand?}
  I -- Hit --> J[Player draws a card]
  J --> K{Player BUST (> 21)?}
  K -- Yes --> L[Player loses]
  K -- No --> H
  I -- Stand --> M[Player turn ends]
  M --> N[Dealer reveals face-down card]
  N --> O{Dealer hand value < 17?}
  O -- Yes --> P1[Dealer draws a card]
  P1 --> O
  O -- No --> Q{Dealer BUST (> 21)?}
  Q -- Yes --> W1[Player wins 1:1]
  Q -- No --> R[Compare hands: Player vs Dealer]
  R --> S{Player value > Dealer value?}
  S -- Yes --> W2[Player wins (1:1 or 3:2)]
  S -- No --> T{Player value = Dealer value?}
  T -- Yes --> P[PUSH (Tie)]
  T -- No --> L[Player loses]
  L --> Z[End: Update chips, new round?]
  P --> Z
  W1 --> Z
  W2 --> Z
```