Kings-Eunuch/kings-eunuch/ARCHITECTURE.md

# King's Eunuch - Architecture Plan

## Vision
A poker training tool that helps players calibrate hand strength and learn game theory, eventually extensible to support a poker bot.

## Design Principles
1. **Separation of Concerns** - Keep game rules separate from probability calculations separate from AI/training logic
2. **Extensibility** - Design for both training scenarios AND bot decision-making
3. **Testability** - Each component should be independently testable
4. **Clarity over Cleverness** - Code should be readable and educational

---

## Layer 1: Core Card/Hand System ✓ COMPLETED

**Purpose:** Represent cards and basic hand structures

**Components:**
- `Card` - Individual playing card (rank + suit)
- `Suit` enum - Spades, Hearts, Diamonds, Clubs
- `Rank` enum - Two through Ace
- `Hand` - Collection of cards

**Status:** ✓ Basic implementation complete
- Card parsing from strings
- Hand creation and card addition
- Error handling with `Result` types

---

## Layer 2: Hand Evaluation (NEXT STEP)

**Purpose:** Determine poker hand rankings and compare hands

**Components Needed:**

### 2.1 HandRank enum
```rust
enum HandRank {
    HighCard,
    Pair,
    TwoPair,
    ThreeOfAKind,
    Straight,
    Flush,
    FullHouse,
    FourOfAKind,
    StraightFlush,
    RoyalFlush,
}
```

### 2.2 HandEvaluator
**Responsibilities:**
- Analyze a hand of 5-7 cards
- Determine the best 5-card poker hand
- Return a `HandRank` + relevant cards (kickers)

**Key Functions:**
- `evaluate_hand(cards: &[Card]) -> HandRank`
- `is_flush(cards: &[Card]) -> bool`
- `is_straight(cards: &[Card]) -> bool`
- `find_pairs(cards: &[Card]) -> Vec<Rank>`
- etc.

### 2.3 Hand Comparison
**Responsibilities:**
- Compare two evaluated hands
- Determine winner (including kicker logic)

**Key Functions:**
- `compare_hands(hand1: &Hand, hand2: &Hand) -> Ordering`

---

## Layer 3: Game State (FUTURE)

**Purpose:** Model the state of a poker game at any point

**Components Needed:**

### 3.1 GameState struct
```rust
struct GameState {
    // Cards
    player_hole_cards: Vec<Card>,      // Your 2 cards
    community_cards: Vec<Card>,        // 0-5 board cards

    // Game info
    stage: GameStage,                  // Preflop, Flop, Turn, River
    pot: u32,

    // Opponent modeling (for training scenarios)
    num_opponents: u8,
    known_opponent_cards: Vec<Card>,   // Usually empty, for training
}

enum GameStage {
    Preflop,
    Flop,
    Turn,
    River,
}
```

### 3.2 Deck Management
```rust
struct Deck {
    cards: Vec<Card>,
}
```
- Generate full 52-card deck
- Remove known cards
- Shuffle and deal

---

## Layer 4: Probability Engine (FUTURE)

**Purpose:** Calculate winning probabilities and equity

**Approach:** Monte Carlo Simulation
1. Take current game state
2. Generate N random completions of unknown cards
3. Evaluate each scenario
4. Count wins/losses/ties
5. Return equity percentage

**Components:**

### 4.1 Simulator
```rust
struct Simulator {
    known_cards: Vec<Card>,
    remaining_deck: Vec<Card>,
}
```

**Key Functions:**
- `calculate_equity(state: &GameState, simulations: u32) -> f64`
- `run_simulation(state: &GameState) -> WinLossTie`
- `deal_random_completion(state: &GameState) -> CompleteHand`

### 4.2 Equity Calculator
- Handle different scenarios (heads-up, multi-way)
- Account for known opponent ranges (advanced)

---

## Layer 5: Training System (FUTURE)

**Purpose:** Present scenarios and quiz users

**Components:**

### 5.1 Scenario Generator
```rust
struct Scenario {
    description: String,
    game_state: GameState,
    question: Question,
    correct_answer: Answer,
}

enum Question {
    WhatIsYourEquity,
    ShouldYouCall { pot_odds: f64 },
    WhatIsExpectedValue { bet_size: u32 },
}
```

### 5.2 Training Session
- Present scenarios
- Collect user answers
- Calculate accuracy
- Track progress over time
- Adaptive difficulty (like Duolingo)

---

## Layer 6: Bot/AI (FAR FUTURE)

**Purpose:** Make optimal poker decisions

**Components:**
- Decision engine (using equity calculations)
- Range analysis
- GTO (Game Theory Optimal) solver
- Exploit strategies

---

## Implementation Roadmap

### Phase 1: Foundation (Current)
- [x] Basic card representation
- [x] Hand struct
- [x] Card parsing
- [ ] **Hand evaluation** ← YOU ARE HERE
- [ ] Hand comparison

### Phase 2: Game Mechanics
- [ ] Deck implementation
- [ ] GameState struct
- [ ] Deal cards from deck
- [ ] Track game stages

### Phase 3: Probability
- [ ] Monte Carlo simulator
- [ ] Equity calculator
- [ ] Basic probability scenarios

### Phase 4: Training
- [ ] Scenario system
- [ ] Quiz mechanics
- [ ] User progress tracking
- [ ] CLI training interface

### Phase 5: Advanced
- [ ] Expected value calculations
- [ ] Pot odds / implied odds
- [ ] Range analysis
- [ ] Bot decision making

---

## Learning Path Notes

**Current Rust Concepts Learned:**
- Enums and structs
- Option<T> and Result<T, E>
- Generics (the `<>` brackets)
- Pattern matching with `match`
- Borrowing with `&`
- Methods and `impl` blocks

**Next Rust Concepts to Learn:**
- Traits (for comparison, ordering)
- Sorting and iterators
- HashMap (for counting card ranks)
- More advanced pattern matching
- Testing with `#[test]`

---

## File Structure (Proposed)

```
src/
├── lib.rs                 # Module declarations
├── main.rs               # CLI entry point / testing
├── translation.rs        # Card, Suit, Rank ✓
├── hand.rs              # Hand struct ✓
├── evaluation.rs        # Hand evaluation (NEXT)
├── game_state.rs        # Game state modeling
├── simulator.rs         # Monte Carlo simulation
├── training/
│   ├── mod.rs
│   ├── scenario.rs      # Training scenarios
│   └── session.rs       # Training sessions
└── bot/
    ├── mod.rs
    └── decision.rs      # Bot logic
```

---

*Last updated: 2026-01-02*