# cookpete/poker-odds architecture

> Architecture diagram of the GitHub repository cookpete/poker-odds, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cookpete/poker-odds
- Repository: https://github.com/cookpete/poker-odds

## Overview

##### Project type and purpose
- This is a Node.js‐based command-line tool (and companion JS library) called “poker-odds,” designed to calculate poker hand probabilities via Monte Carlo or exhaustive simulation.
- It provides both a CLI executable (installed globally via npm/yarn) and an exportable API (`calculateEquity`) for embedding in other JS projects.

##### File structure
- Top level
- Configuration: .gitignore, .npmignore, .travis.yml, package.json, CHANGELOG.md, LICENSE.md, README.md
- Data file: lookup.json (precomputed rank lookup table)
- src/ — business logic
- src/bin/
– generate-lookup.js → regenerates lookup.json
– poker-odds.js → CLI entrypoint for running odds calculations
- src/calculate.js → core simulation engine (Monte Carlo/exhaustive)
- src/console.js → command-line argument parsing, output formatting
- src/deck.js → deck & card‐dealing utilities
- src/rank.js → hand‐ranking logic using lookup.json
- test/ — unit tests for each module

##### README for additional insights
- Confirms CLI flags, API usage, default behaviors, and no external dependencies beyond Node.js
- Emphasizes two modes: Monte Carlo (iterations) and exhaustive
- Shows example outputs and library import signature

##### Main components
A. CLI Layer
- Bin wrapper (`poker-odds.js`) → invokes console.js
- Argument parser & formatter (console.js) → translates flags to function calls
B. Core Engine
- calculate.js → implements simulation loops, calls sub‐modules
C. Domain Modules
- deck.js → card generation, shuffling, dealing
- rank.js → hand evaluation, uses lookup.json table
D. Data Store
- lookup.json → precomputed 52-card lookup table for fast ranking
- generate-lookup.js → utility to rebuild lookup.json when rules change
E. External API
- calculateEquity export → available for programmatic use
F. Tests
- test suite for calculate, console, rank, utils

##### Relationships and interactions
- The CLI bin script calls console.js → console.js parses inputs and calls calculateEquity in calculate.js
- calculate.js orchestrates:
- deck.js for dealing cards
- rank.js for evaluating hands via lookup.json
- utils.js for random draws / combinations
- Data flows: user input → CLI → simulation → output back to console
- generate-lookup.js is a standalone tool that writes to lookup.json (not invoked by CLI)
- External consumers import calculateEquity directly, bypassing the CLI

##### Architectural patterns and design principles
- Modular separation: CLI vs core engine vs domain logic vs data
- Single Responsibility: each JS module has one concern
- Data-driven ranking: precomputed lookup.json speeds up hand evaluation
- Extensibility point: update lookup.json via generate-lookup, plug in custom deck rules if needed

##### Relevant technologies
- Node.js (no external npm dependencies)
- Standard CLI argument parsing (built-in)
- File I/O for lookup.json
- JSON data representation for quick lookups

##### Essential elements
- Don’t omit the generate-lookup utility—it’s the only way to refresh rank data
- Test suite tangentially or in an appendix to indicate coverage
- Clearly distinguish between binary entrypoints and library exports

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        POKERBIN["poker-odds.js"]:::cli
        Console["console.js"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        Calculate["calculate.js"]:::core
    end

    %% Domain Modules
    subgraph "Domain Modules"
        Deck["deck.js"]:::domain
        Rank["rank.js"]:::domain
        Utils["utils.js"]:::domain
    end

    %% Data Store
    subgraph "Data Store"
        Lookup["lookup.json"]:::data
    end

    %% Utility for Data
    Generate["generate-lookup.js"]:::dataTool

    %% External API
    API["External API: calculateEquity"]:::external

    %% Test Suite
    subgraph "Test Suite"
        TCalc["test/calculate.js"]:::test
        TConsole["test/console.js"]:::test
        TRank["test/rank.js"]:::test
        TUtils["test/utils.js"]:::test
    end

    %% Relationships
    POKERBIN -->|"invoke"| Console
    Console -->|"call calculateEquity"| Calculate

    Calculate -->|"shuffle & deal"| Deck
    Calculate -->|"evaluate hand"| Rank
    Calculate -->|"helpers"| Utils

    Rank -->|"lookup"| Lookup
    Generate -->|"writes"| Lookup

    API -->|"import"| Calculate

    TCalc --> Calculate
    TConsole --> Console
    TRank --> Rank
    TUtils --> Utils

    %% Click Events
    click POKERBIN "https://github.com/cookpete/poker-odds/blob/master/src/bin/poker-odds.js"
    click Console "https://github.com/cookpete/poker-odds/blob/master/src/console.js"
    click Calculate "https://github.com/cookpete/poker-odds/blob/master/src/calculate.js"
    click Deck "https://github.com/cookpete/poker-odds/blob/master/src/deck.js"
    click Rank "https://github.com/cookpete/poker-odds/blob/master/src/rank.js"
    click Utils "https://github.com/cookpete/poker-odds/blob/master/src/utils.js"
    click Lookup "https://github.com/cookpete/poker-odds/blob/master/lookup.json"
    click Generate "https://github.com/cookpete/poker-odds/blob/master/src/bin/generate-lookup.js"
    click TCalc "https://github.com/cookpete/poker-odds/blob/master/test/calculate.js"
    click TConsole "https://github.com/cookpete/poker-odds/blob/master/test/console.js"
    click TRank "https://github.com/cookpete/poker-odds/blob/master/test/rank.js"
    click TUtils "https://github.com/cookpete/poker-odds/blob/master/test/utils.js"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#034EA2,stroke-width:1px
    classDef core fill:#DFF7D0,stroke:#118C00,stroke-width:1px
    classDef domain fill:#FFF4C1,stroke:#A68D00,stroke-width:1px
    classDef data fill:#FFE8C1,stroke:#D97700,stroke-width:1px
    classDef dataTool fill:#FFEDD5,stroke:#D97706,stroke-width:1px
    classDef external fill:#E5D0FF,stroke:#6B21A8,stroke-width:1px
    classDef test fill:#F0F0F0,stroke:#666666,stroke-width:1px,stroke-dasharray: 2 2
```
