# nikhilthadani/stake-math-sdk-vicecartel architecture

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

- Interactive diagram: https://gitdiagram.com/nikhilthadani/stake-math-sdk-vicecartel
- Repository: https://github.com/nikhilthadani/stake-math-sdk-vicecartel

## Overview

Stake Engine Math SDK defines game-specific rules and configuration, simulates outcomes into event books and lookup data, and optimizes win distributions. The principal workflow is to run a game, generate boards and resolve game mechanics, record wins/events, then write simulation and publish artifacts; analysis and AWS upload are supporting capabilities. The tree and excerpts establish the shared runtime layers, but do not show the complete game-run orchestration, so uncertain call links are omitted. Optimization and analytics are represented at the documented capability level where their wiring is not sampled.

Main entry points: [`games/template/run.py`](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/run.py) (Game runner), [`src/state/run_sims.py`](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/run_sims.py) (Simulation runner), [`games/template/game_executables.py`](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_executables.py) (Game rules), [`src/calculations/board.py`](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/calculations/board.py) (Board generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_game_definitions["Game definitions"]
  node_game_run["Game runner<br/>[run.py]"]
  node_game_config["Game configuration<br/>[game_config.py]"]
  node_game_rules["Game rules"]
  node_game_overrides["Game overrides<br/>[game_override.py]"]
end

subgraph group_simulation_runtime["Simulation runtime"]
  node_state["Game state<br/>[state.py]"]
  node_sim_runner["Simulation runner<br/>[run_sims.py]"]
  node_board["Board generation<br/>[board.py]"]
  node_mechanics["Game calculations"]
  node_events["Event recording<br/>[events.py]"]
  node_win_manager["Win accounting<br/>[win_manager.py]"]
  node_books["Book state<br/>[books.py]"]
end

subgraph group_outputs_optimization["Outputs and optimization"]
  node_outputs["Artifact writing<br/>[write_data.py]"]
  node_output_paths["Output paths"]
  node_optimization["Distribution optimizer<br/>[main.rs]"]
  node_optimization_config["Optimization setup"]
end

subgraph group_support_tools["Analysis and delivery"]
  node_analytics["Game analytics<br/>[run_analysis.py]"]
  node_distribution_analysis["Distribution analysis"]
  node_aws_upload["AWS upload<br/>[aws_upload.py]"]
end

node_user(("Game developer"))
node_s3[("Amazon S3")]

node_user -->|"runs game"| node_game_run
node_game_run -->|"loads settings"| node_game_config
node_game_run -->|"starts simulations"| node_sim_runner
node_sim_runner -->|"updates state"| node_state
node_game_rules -->|"draws board"| node_board
node_board -->|"provides board"| node_mechanics
node_mechanics -->|"updates wins"| node_win_manager
node_game_rules -->|"records events"| node_events
node_events -->|"adds events"| node_books
node_win_manager -->|"tracks payouts"| node_state
node_sim_runner -->|"writes results"| node_outputs
node_outputs -->|"uses paths"| node_output_paths
node_user -->|"sets targets"| node_optimization_config
node_optimization_config -.->|"configures"| node_optimization
node_user -->|"analyzes results"| node_analytics
node_analytics -->|"calculates metrics"| node_distribution_analysis
node_user -->|"requests upload"| node_aws_upload
node_aws_upload -.->|"uploads artifacts"| node_s3

click node_game_run "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/run.py"
click node_game_config "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_config.py"
click node_game_rules "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_executables.py"
click node_game_overrides "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_override.py"
click node_state "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/state.py"
click node_sim_runner "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/run_sims.py"
click node_board "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/calculations/board.py"
click node_mechanics "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/tree/main/src/calculations"
click node_events "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/events/events.py"
click node_win_manager "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/wins/win_manager.py"
click node_books "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/books.py"
click node_outputs "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/write_data/write_data.py"
click node_output_paths "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/config/output_filenames.py"
click node_optimization "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/optimization_program/src/main.rs"
click node_optimization_config "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/optimization_program/optimization_config.py"
click node_analytics "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/utils/game_analytics/run_analysis.py"
click node_distribution_analysis "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/utils/analysis/distribution_functions.py"
click node_aws_upload "https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/uploads/aws_upload.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_game_run,node_game_config,node_game_rules,node_game_overrides toneBlue
class node_state,node_sim_runner,node_board,node_mechanics,node_events,node_win_manager,node_books,node_s3 toneAmber
class node_outputs,node_output_paths,node_optimization,node_optimization_config toneMint
class node_analytics,node_distribution_analysis,node_aws_upload toneRose
class node_user toneIndigo
```

## Components

### Game definitions

- [Game runner](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/run.py): `games/template/run.py`
- [Game configuration](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_config.py): `games/template/game_config.py`
- [Game rules](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_executables.py): `games/template/game_executables.py`
- [Game overrides](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/games/template/game_override.py): `games/template/game_override.py`

### Simulation runtime

- [Game state](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/state.py): `src/state/state.py`
- [Simulation runner](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/run_sims.py): `src/state/run_sims.py`
- [Board generation](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/calculations/board.py): `src/calculations/board.py`
- [Game calculations](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/tree/main/src/calculations): `src/calculations`
- [Event recording](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/events/events.py): `src/events/events.py`
- [Win accounting](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/wins/win_manager.py): `src/wins/win_manager.py`
- [Book state](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/state/books.py): `src/state/books.py`

### Outputs and optimization

- [Artifact writing](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/write_data/write_data.py): `src/write_data/write_data.py`
- [Output paths](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/src/config/output_filenames.py): `src/config/output_filenames.py`
- [Distribution optimizer](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/optimization_program/src/main.rs): `optimization_program/src/main.rs`
- [Optimization setup](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/optimization_program/optimization_config.py): `optimization_program/optimization_config.py`

### Analysis and delivery

- [Game analytics](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/utils/game_analytics/run_analysis.py): `utils/game_analytics/run_analysis.py`
- [Distribution analysis](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/utils/analysis/distribution_functions.py): `utils/analysis/distribution_functions.py`
- [AWS upload](https://github.com/nikhilthadani/stake-math-sdk-vicecartel/blob/main/uploads/aws_upload.py): `uploads/aws_upload.py`

### Other components

- **Game developer**
- **Amazon S3**

## Connections

- Game developer → Game runner: runs game
- Game runner → Game configuration: loads settings
- Game runner → Simulation runner: starts simulations
- Simulation runner → Game state: updates state
- Game rules → Board generation: draws board
- Board generation → Game calculations: provides board
- Game calculations → Win accounting: updates wins
- Game rules → Event recording: records events
- Event recording → Book state: adds events
- Win accounting → Game state: tracks payouts
- Simulation runner → Artifact writing: writes results
- Artifact writing → Output paths: uses paths
- Game developer → Optimization setup: sets targets
- Optimization setup → Distribution optimizer: configures
- Game developer → Game analytics: analyzes results
- Game analytics → Distribution analysis: calculates metrics
- Game developer → AWS upload: requests upload
- AWS upload → Amazon S3: uploads artifacts