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

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

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

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

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

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)

• Basic card representation
• Hand struct
• 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 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