# stakeengine/math-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/stakeengine/math-sdk
- Repository: https://github.com/stakeengine/math-sdk

## Overview

##### Project Type and Purpose
- This is a Python-based Software Development Kit (SDK) for defining slot-game rules, simulating outcomes, and optimizing win distributions.
- It also includes an optional Rust/Cargo “optimization_program” for performance-critical distribution optimization.
- Sample “games” folders act as plug-in definitions demonstrating SDK usage.
- Auxiliary components: AWS upload tools, utilities for analysis, and MkDocs-based documentation.

##### Top-Level Components
- CLI Orchestrator (Makefile / setup.py / run scripts)
- Core SDK (src/)
- config: bet modes, constants, paths
- calculations: board, cluster, lines, scatter, tumble, ways, statistics
- events: event definitions and logic
- executables: wrappers to generate game executables
- state: game-state modeling and simulation runner
- wins: win-manager and multiplier strategies
- write_data: output writing of configs, force files, simulation results
- Optimization Engine (optimization_program/)
- Rust-based binary invoked via run_script.py or cargo directly
- Game Definitions (games/)
- Multiple subfolders (cluster, expwilds, lines, scatter, ways) each implement a standardized interface (game_config, game_events, game_calculations, gamestate, run.py)
- AWS Upload Service (uploads/)
- AWS S3 uploader classes, constants, env config
- Utilities (utils/)
- Analysis, verification, decompress, game analytics
- Testing (tests/)
- Unit tests for win calculations and core logic
- Documentation (docs/, mkdocs.yml)
- MkDocs source, styling, and assets

##### Interactions and Data Flow
- Developer invokes CLI (Make targets or setup.py) → selects a game or generic simulation →
- SDK config module loads parameters → initial game state instantiated by state module →
- Event and calculations modules simulate spins, outcomes →
- wins module computes payouts →
- write_data module writes out JSON/CSV results and config files →
- optionally optimization_program (Rust) is called to refine distribution parameters →
- results can be uploaded via uploads module to AWS S3 →
- utilities can post-process or analyze results →
- tests validate core SDK logic in CI.

##### Architectural Patterns and Design Principles
- Layered modular architecture:
- Configuration Layer → Business Logic Layer (calculations & events) → State & Simulation Layer → Output/Persistence Layer → External Services
- Plugin-style game definitions decoupled from core SDK
- Separation of concerns: each folder/module has a single responsibility
- CLI as thin orchestration layer
- Use of an external high-performance Rust component for optimization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Orchestrator
    CLI["CLI Orchestrator"]:::cli
    click CLI "https://github.com/stakeengine/math-sdk/tree/main/Makefile"
    click CLI "https://github.com/stakeengine/math-sdk/blob/main/setup.py"

    %% Core SDK Layers
    subgraph "Core SDK" 
        direction TB
        subgraph "Configuration Layer"
            config["Configuration Module"]:::config
            click config "https://github.com/stakeengine/math-sdk/tree/main/src/config/"
        end
        subgraph "Business Logic Layer"
            calc["Calculations Module"]:::business
            events["Events Module"]:::business
            click calc "https://github.com/stakeengine/math-sdk/tree/main/src/calculations/"
            click events "https://github.com/stakeengine/math-sdk/tree/main/src/events/"
        end
        subgraph "State & Simulation Layer"
            state["State & Simulation"]:::state
            click state "https://github.com/stakeengine/math-sdk/tree/main/src/state/"
        end
        subgraph "Win Management Layer"
            wins["Win Management"]:::wins
            click wins "https://github.com/stakeengine/math-sdk/tree/main/src/wins/"
        end
        subgraph "Output & Persistence Layer"
            write["Data Output & Persistence"]:::output
            click write "https://github.com/stakeengine/math-sdk/tree/main/src/write_data/"
        end
        exec["Executables Wrapper"]:::business
        click exec "https://github.com/stakeengine/math-sdk/blob/main/src/executables/executables.py"
    end

    %% Game Plug-ins
    subgraph "Game Definitions (Plugins)" 
        direction TB
        cluster["Cluster Example"]:::plugins
        expwilds["ExpWilds Example"]:::plugins
        lines["Lines Example"]:::plugins
        scatter["Scatter Example"]:::plugins
        ways["Ways Example"]:::plugins
        template["Template Plugin"]:::plugins
        click cluster "https://github.com/stakeengine/math-sdk/tree/main/games/0_0_cluster/"
        click expwilds "https://github.com/stakeengine/math-sdk/tree/main/games/0_0_expwilds/"
        click lines "https://github.com/stakeengine/math-sdk/tree/main/games/0_0_lines/"
        click scatter "https://github.com/stakeengine/math-sdk/tree/main/games/0_0_scatter/"
        click ways "https://github.com/stakeengine/math-sdk/tree/main/games/0_0_ways/"
        click template "https://github.com/stakeengine/math-sdk/tree/main/games/template/"
    end

    %% Optimization Engine
    opt["Rust Optimization Engine (Cargo Binary)"]:::rust
    click opt "https://github.com/stakeengine/math-sdk/blob/main/optimization_program/src/main.rs"
    subgraph "Optimization Config & Runner"
        direction TB
        optcfg["Optimization Config"]:::rust
        optrun["Optimizer Invoker Script"]:::rust
        click optcfg "https://github.com/stakeengine/math-sdk/blob/main/optimization_program/optimization_config.py"
        click optrun "https://github.com/stakeengine/math-sdk/blob/main/optimization_program/run_script.py"
    end

    %% AWS Upload Service
    subgraph "AWS Upload Service"
        direction TB
        aws1["S3 Uploader Classes"]:::external
        aws2["AWS Constants"]:::external
        aws3["Upload Logic"]:::external
        click aws1 "https://github.com/stakeengine/math-sdk/blob/main/uploads/aws_classes.py"
        click aws2 "https://github.com/stakeengine/math-sdk/blob/main/uploads/aws_constants.py"
        click aws3 "https://github.com/stakeengine/math-sdk/blob/main/uploads/aws_upload.py"
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        util1["Analysis Helpers"]:::utils
        util2["Decompression"]:::utils
        util3["Game Analytics Suite"]:::utils
        util4["File Hashing"]:::utils
        util5["RGS Verification"]:::utils
        util6["Lookup Swapping"]:::utils
        click util1 "https://github.com/stakeengine/math-sdk/tree/main/utils/analysis/"
        click util2 "https://github.com/stakeengine/math-sdk/blob/main/utils/decompress_zstd.py"
        click util3 "https://github.com/stakeengine/math-sdk/tree/main/utils/game_analytics/"
        click util4 "https://github.com/stakeengine/math-sdk/blob/main/utils/get_file_hash.py"
        click util5 "https://github.com/stakeengine/math-sdk/blob/main/utils/rgs_verification.py"
        click util6 "https://github.com/stakeengine/math-sdk/blob/main/utils/swap_lookups.py"
    end

    %% Testing and Documentation
    tests["Test Suite (pytest)"]:::tests
    click tests "https://github.com/stakeengine/math-sdk/tree/main/tests/win_calculations/"
    docs["Documentation (MkDocs)"]:::docs
    click docs "https://github.com/stakeengine/math-sdk/tree/main/docs/"

    %% Data Store
    csv["Results (JSON/CSV)"]:::data

    %% Flow Connections
    CLI -->|"load config"| config
    config -->|"init game state"| state
    state -->|"simulate"| calc
    state -->|"simulate"| events
    calc -->|"compute payouts"| wins
    events -->|"emit events"| wins
    wins -->|"generate results"| write
    write -->|"write JSON/CSV"| csv
    CLI -->|"invoke optimizer"| opt
    opt --> optcfg
    opt --> optrun
    write -->|"upload results"| aws3
    csv --> aws3
    write --> util1
    write --> util3
    util2 --> write
    util4 --> util5
    util6 --> util1

    tests --> config
    tests --> calc
    tests --> events
    tests --> wins

    docs --> config
    docs --> calc
    docs --> state

    %% Styling
    classDef cli fill:#f9c2ff,stroke:#333,stroke-width:1px;
    classDef config fill:#b3d9ff,stroke:#333,stroke-width:1px;
    classDef business fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef state fill:#b2f0f0,stroke:#333,stroke-width:1px;
    classDef wins fill:#d4f5b2,stroke:#333,stroke-width:1px;
    classDef output fill:#fff2b2,stroke:#333,stroke-width:1px;
    classDef plugins fill:#d9ffd9,stroke:#333,stroke-width:1px;
    classDef rust fill:#e3ccff,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef external fill:#ffdbb3,stroke:#333,stroke-width:1px;
    classDef utils fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef tests fill:#ffcccc,stroke:#333,stroke-width:1px;
    classDef docs fill:#d9bcff,stroke:#333,stroke-width:1px;
    classDef data fill:#ffffff,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2;
```
