blackjack/docs/roadmap.md

# 🗺️ Blackjack Implementation Roadmap with Method Signatures (Final, Clean Markdown)

This document provides a detailed, class-by-class breakdown of the Blackjack project, including the expected method signatures and descriptions of class interactions, using only standard Markdown syntax.

---

## Phase 1: The Basics – Card and Deck

### 1. `Card` Class

The `Card` class is a **static data container**.

| Component | Signature / Example Value | Purpose |
| :--- | :--- | :--- |
| **Constructor** | `def __init__(self, rank: str, suit: str, value: int)` | Initializes the card with its fixed properties. |
| **Attribute** | `- rank: str` | `'A', 'K', '3'` |
| **Attribute** | `- suit: str` | `'Spades', 'Hearts'` |
| **Attribute** | `- value: int` | **10** (for K, Q, J) or **11** (for A). This is the card's **initial** value. |
| **Method** | `def __str__(self) -> str` | Returns a human-readable string (e.g., `"Queen of Diamonds"`). |
| **Call Example** | `print(my_card)` | Used automatically by the `print()` function. |

### 2. `Deck` Class

The `Deck` manages the card pool, creating and distributing the `Card` objects.

| Component | Signature / Example Call | Purpose |
| :--- | :--- | :--- |
| **Constructor** | `def __init__(self)` | Creates all 52 unique `Card` objects and stores them in `self.cards`. |
| **Attribute** | `- cards: List[Card]` | The internal list holding all 52 `Card` objects. |
| **Method** | `def shuffle(self) -> None` | Randomly **reorders** the elements in the internal `cards` list. |
| **Call Example** | `my_deck.shuffle()` | Called at the start of every new round. |
| **Method** | `def deal_card(self) -> Card` | **Removes and returns** the top card (e.g., using a list's `pop()` method). |
| **Call Example** | `new_card = my_deck.deal_card()` | Called by `Player.hit()` and the `Game` for initial dealing. |

---

## Phase 2: Core Logic – Hand and Value Calculation

### 3. `Hand` Class

The `Hand` object's role is to ensure the **Blackjack value rules** are always correctly applied, especially the Ace rule.

| Component | Signature / Example Call | Purpose |
| :--- | :--- | :--- |
| **Constructor** | `def __init__(self)` | Initializes `cards` as empty, `value` to **0**, and `aces` to **0**. |
| **Attribute** | `- value: int` | The current, **dynamically adjusted** sum of the cards. |
| **Attribute** | `- aces: int` | Count of Aces held (used for the 1/11 rule). |
| **Method** | `def add_card(self, card: Card) -> None` | **Updates Hand:** Appends `card`, updates `self.value`, increments `self.aces` if needed, and then calls `self.adjust_for_ace()`. |
| **Call Example** | `player_hand.add_card(new_card)` | Called every time a card is drawn. |
| **Method** | `def adjust_for_ace(self) -> None` | **Ace Rule Logic:** Uses a `while` loop: if `value > 21` AND `aces > 0`, it subtracts **10** from `value` and decrements `aces`. |
| **Call Example** | (Internal call from `add_card`) | Called automatically after every card addition. |

---

## Phase 3: The Actors and Their Actions

### 4. `Player` Class (Base)

The `Player` class represents any participant who holds a hand and makes decisions.

| Component | Signature / Example Call | Purpose |
| :--- | :--- | :--- |
| **Constructor** | `def __init__(self, name: str, chips: int)` | Sets up the player's name, starting chips, and a new `Hand` object. |
| **Attribute** | `- hand: Hand` | The specific `Hand` object associated with this player. |
| **Method** | `def hit(self, deck: Deck) -> None` | **Draws Card:** Retrieves a card from the `Deck` (`deck.deal_card()`) and passes it to the internal hand (`self.hand.add_card(...)`). |
| **Call Example** | `player.hit(my_deck)` | Called when a player chooses to draw a card. |
| **Method** | `def stand(self) -> None` | **Ends Turn:** Sets an internal state (e.g., `$is\_standing = True$`) to signal the end of the player's draw phase. |
| **Call Example** | `player.stand()` | Called when a player is satisfied with their hand. |

### 5. `Dealer` Class (Inherits from `Player`)

The `Dealer` inherits all player functionality but has a specific, automated turn behavior.

| Component | Signature / Example Call | Purpose |
| :--- | :--- | :--- |
| **Method** | `def play(self, deck: Deck) -> None` | **Automated Turn:** Implements the fixed dealer rule: uses a `while` loop to continuously call `self.hit(deck)` as long as `self.hand.value < 17`. |
| **Call Example** | `dealer.play(my_deck)` | Called only after the human player has finished their turn. |

---

## Phase 4: Game Orchestration and Resolution

### 6. `Game` Class

The `Game` class is the central coordinator, managing the flow of the entire round, from setup to payout.

| Component | Signature / Example Call | Purpose |
| :--- | :--- | :--- |
| **Constructor** | `def __init__(self)` | Creates instances of `Deck`, `Player`, and `Dealer`. |
| **Attribute** | `- deck: Deck` | The `Deck` instance used for card distribution. |
| **Attribute** | `- player: Player` | The human `Player` instance. |
| **Attribute** | `- dealer: Dealer` | The `Dealer` instance. |
| **Method** | `def play_round(self) -> None` | **Main Flow Controller:** Manages dealing, player input loops, the dealer's `play()` call, and calling `compare_hands()`. |
| **Call Example** | `my_game.play_round()` | The main function that drives one full round of Blackjack. |
| **Method** | `def show_cards(self, hide_dealer: bool) -> None` | Displays the cards. The boolean determines if the dealer's second card is shown or concealed. |
| **Call Example** | `game.show_cards(hide_dealer=True)` | Called at the beginning of the round. |
| **Method** | `def compare_hands(self, bet: int) -> str` | **Resolution/Payout:** Compares final hand values, checks for Bust, Blackjack, and highest value. **Updates `player.chips`** based on the outcome and the `bet`. Returns the result string (e.g., "Player Wins!"). |
| **Call Example** | `result = game.compare_hands(50)` | Called once both players stand or bust. |