# trinistr/dicey architecture

> Architecture diagram of the GitHub repository trinistr/dicey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trinistr/dicey
- Repository: https://github.com/trinistr/dicey

## Overview

#### Purpose and Delivery

Dicey is a Ruby gem for modeling dice, rolling them, and calculating complete outcome weight/probability distributions. It is primarily a library with command-line delivery; the referenced online UI is external to this repository.

Gem/library root: `lib/dicey.rb`; package metadata: `dicey.gemspec`. CLI executables: `exe/dicey` and `exe/dicey-to-gnuplot`.

#### Entry Points and CLI Orchestration

`Dicey::CLI` is the command boundary: it parses arguments/options, builds dice, selects calculation or roll mode, and directs output formatting. `Dicey::CLI::CalculatorRunner` and `Dicey::CLI::Roller` separate distribution calculation from random-roll execution. The GNUplot executable supports a pipeline from Dicey’s graph-oriented output to a PNG-producing external tool.

Paths: `lib/dicey/cli.rb`, `lib/dicey/cli/options.rb`, `lib/dicey/cli/calculator_runner.rb`, `lib/dicey/cli/roller.rb`, `lib/dicey/cli/blender.rb`.

#### Dice Domain Model

`AbstractDie` is the permissive core representation: a sequence of sides plus mutable current-roll state and shared randomness. `NumericDie` constrains sides to numeric values; `RegularDie` expands a side count into the standard `1..N` range. This hierarchy is the boundary between input construction and both rolling/calculation algorithms.

Paths: `lib/dicey/abstract_die.rb`, `lib/dicey/numeric_die.rb`, `lib/dicey/regular_die.rb`.

#### Input Compilation: DieFoundry

`DieFoundry` parses CLI-style string definitions—counts, ranges, numeric lists, arbitrary/symbolic lists—and produces one die or repeated dice. CLI input is therefore normalized to arrays of domain die objects before operation dispatch. It also enables the same compact notation through the Ruby API.

Path: `lib/dicey/die_foundry.rb`.

#### Distribution Calculation Pipeline

Calculators implement a common contract through `BaseCalculator`: validate dice, estimate complexity, then return an outcome-to-weight or probability hash. `AutoSelector` chooses a usable algorithm according to die type and expected cost. Algorithm boundaries are important: polynomial convolution accepts integer dice; multinomial targets repeated arithmetic dice; binomial targets equal two-sided dice; iterative and empirical cover generic/abstract cases; trivial shortcuts simple inputs.

Paths: `lib/dicey/distribution_calculators/base_calculator.rb`, `lib/dicey/distribution_calculators/auto_selector.rb`, `lib/dicey/distribution_calculators/polynomial_convolution.rb`, `lib/dicey/distribution_calculators/multinomial_coefficients.rb`, `lib/dicey/distribution_calculators/iterative.rb`, `lib/dicey/distribution_calculators/binomial.rb`, `lib/dicey/distribution_calculators/empirical.rb`.

#### Result Interpretation and Presentation

Distribution hashes can feed `DistributionPropertiesCalculator` for descriptive statistics such as modes, moments, and spread. CLI formatters serialize the calculation/roll result into lists, JSON, YAML, null output, or GNUplot-compatible data. Formatting is deliberately downstream of calculation, preserving a library-friendly Hash result.

Paths: `lib/dicey/distribution_properties_calculator.rb`, `lib/dicey/cli/formatters/json_formatter.rb`, `lib/dicey/cli/formatters/yaml_formatter.rb`, `lib/dicey/cli/formatters/gnuplot_formatter.rb`.

#### Runtime, Dependencies, and Operations

The runtime is Ruby, tested across CRuby 3.0+, JRuby, and TruffleRuby, with CI workflows per implementation. `vector_number` supports summable symbolic outcomes; JSON/YAML output depends on their Ruby libraries. GNUplot is an optional external executable used only by the graph pipeline. API signatures are maintained in `sig/dicey.rbs`; documentation deployment is handled by GitHub Actions.

Paths: `.github/workflows/CI.yaml`, `.github/workflows/jruby.yaml`, `.github/workflows/truffle_ruby.yaml`, `sig/dicey.rbs`.

Main entry points: [`lib/dicey/cli.rb`](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli.rb) (CLI), [`lib/dicey/abstract_die.rb`](https://github.com/trinistr/dicey/blob/main/lib/dicey/abstract_die.rb) (AbstractDie), [`lib/dicey/cli/calculator_runner.rb`](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/calculator_runner.rb) (Calculator runner), [`lib/dicey/cli/roller.rb`](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/roller.rb) (Roller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_gem["Dicey gem API<br/>Ruby library root<br/>[dicey.rb]"]
  node_cli["CLI<br/>command boundary<br/>[cli.rb]"]
  node_cli_options["CLI options<br/>argument parser<br/>[options.rb]"]
  node_calculator_runner["Calculator runner<br/>CLI calculation flow"]
  node_roller["Roller<br/>CLI roll flow<br/>[roller.rb]"]
end

subgraph group_domain["Dice domain"]
  node_foundry["DieFoundry<br/>input compiler<br/>[die_foundry.rb]"]
  node_abstract_die["AbstractDie<br/>die base model<br/>[abstract_die.rb]"]
  node_numeric_die["NumericDie<br/>numeric die<br/>[numeric_die.rb]"]
  node_regular_die["RegularDie<br/>standard die<br/>[regular_die.rb]"]
end

subgraph group_calculation["Distribution calculation"]
  node_base_calculator["BaseCalculator<br/>calculator contract<br/>[base_calculator.rb]"]
  node_auto_selector["AutoSelector<br/>algorithm selector<br/>[auto_selector.rb]"]
  node_algorithms["Distribution algorithms<br/>calculator implementations"]
end

subgraph group_presentation["Results and output"]
  node_properties["Distribution properties<br/>statistics calculator"]
  node_formatters["CLI formatters<br/>result serializers<br/>[json_formatter.rb]"]
  node_gnuplot_pipeline["GNUplot pipeline<br/>external graph output<br/>[blender.rb]"]
end

subgraph group_operations["Runtime and operations"]
  node_type_signatures["RBS signatures<br/>API contract<br/>[dicey.rbs]"]
  node_ci["Multi-Ruby CI<br/>compatibility validation<br/>[CI.yaml]"]
end

node_gem -->|"exposes command API"| node_cli
node_cli -->|"parses"| node_cli_options
node_cli -->|"compiles input"| node_foundry
node_cli -->|"calculation mode"| node_calculator_runner
node_cli -->|"roll mode"| node_roller
node_foundry -->|"builds dice"| node_abstract_die
node_numeric_die -->|"specializes"| node_abstract_die
node_regular_die -->|"specializes"| node_numeric_die
node_calculator_runner -->|"selects calculator"| node_auto_selector
node_auto_selector -->|"uses contract"| node_base_calculator
node_auto_selector -->|"chooses"| node_algorithms
node_base_calculator -->|"validates inputs"| node_abstract_die
node_algorithms -->|"calculates distributions"| node_abstract_die
node_roller -->|"rolls"| node_abstract_die
node_calculator_runner -->|"summarizes distribution"| node_properties
node_calculator_runner -->|"formats result"| node_formatters
node_roller -->|"formats result"| node_formatters
node_formatters -->|"graph data"| node_gnuplot_pipeline
node_gem -.->|"typed API"| node_type_signatures
node_ci -.->|"tests runtimes"| node_gem

click node_gem "https://github.com/trinistr/dicey/blob/main/lib/dicey.rb"
click node_cli "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli.rb"
click node_cli_options "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/options.rb"
click node_calculator_runner "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/calculator_runner.rb"
click node_roller "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/roller.rb"
click node_foundry "https://github.com/trinistr/dicey/blob/main/lib/dicey/die_foundry.rb"
click node_abstract_die "https://github.com/trinistr/dicey/blob/main/lib/dicey/abstract_die.rb"
click node_numeric_die "https://github.com/trinistr/dicey/blob/main/lib/dicey/numeric_die.rb"
click node_regular_die "https://github.com/trinistr/dicey/blob/main/lib/dicey/regular_die.rb"
click node_base_calculator "https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/base_calculator.rb"
click node_auto_selector "https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/auto_selector.rb"
click node_algorithms "https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/polynomial_convolution.rb"
click node_properties "https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_properties_calculator.rb"
click node_formatters "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/formatters/json_formatter.rb"
click node_gnuplot_pipeline "https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/blender.rb"
click node_type_signatures "https://github.com/trinistr/dicey/blob/main/sig/dicey.rbs"
click node_ci "https://github.com/trinistr/dicey/blob/main/.github/workflows/CI.yaml"

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_gem,node_cli,node_cli_options,node_calculator_runner,node_roller toneBlue
class node_foundry,node_abstract_die,node_numeric_die,node_regular_die toneAmber
class node_base_calculator,node_auto_selector,node_algorithms toneMint
class node_properties,node_formatters,node_gnuplot_pipeline toneRose
class node_type_signatures,node_ci toneIndigo
```

## Components

### Delivery

- [Dicey gem API](https://github.com/trinistr/dicey/blob/main/lib/dicey.rb): Ruby library root · Library entry point and public API. · `lib/dicey.rb`
- [CLI](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli.rb): command boundary · Parses options and dispatches rolling or calculation. · `lib/dicey/cli.rb`
- [CLI options](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/options.rb): argument parser · `lib/dicey/cli/options.rb`
- [Calculator runner](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/calculator_runner.rb): CLI calculation flow · `lib/dicey/cli/calculator_runner.rb`
- [Roller](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/roller.rb): CLI roll flow · `lib/dicey/cli/roller.rb`

### Dice domain

- [DieFoundry](https://github.com/trinistr/dicey/blob/main/lib/dicey/die_foundry.rb): input compiler · Compiles compact die definitions into die objects. · `lib/dicey/die_foundry.rb`
- [AbstractDie](https://github.com/trinistr/dicey/blob/main/lib/dicey/abstract_die.rb): die base model · Sides, mutable roll state, and shared randomness. · `lib/dicey/abstract_die.rb`
- [NumericDie](https://github.com/trinistr/dicey/blob/main/lib/dicey/numeric_die.rb): numeric die · `lib/dicey/numeric_die.rb`
- [RegularDie](https://github.com/trinistr/dicey/blob/main/lib/dicey/regular_die.rb): standard die · Expands a side count into 1..N. · `lib/dicey/regular_die.rb`

### Distribution calculation

- [BaseCalculator](https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/base_calculator.rb): calculator contract · Validates dice and estimates calculation cost. · `lib/dicey/distribution_calculators/base_calculator.rb`
- [AutoSelector](https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/auto_selector.rb): algorithm selector · Chooses a calculation strategy by die type and cost. · `lib/dicey/distribution_calculators/auto_selector.rb`
- [Distribution algorithms](https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_calculators/polynomial_convolution.rb): calculator implementations · Polynomial, multinomial, iterative, binomial, and empirical strategies. · `lib/dicey/distribution_calculators/polynomial_convolution.rb`

### Results and output

- [Distribution properties](https://github.com/trinistr/dicey/blob/main/lib/dicey/distribution_properties_calculator.rb): statistics calculator · Derives modes, moments, and spread from distributions. · `lib/dicey/distribution_properties_calculator.rb`
- [CLI formatters](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/formatters/json_formatter.rb): result serializers · JSON, YAML, GNUplot, list, and null output. · `lib/dicey/cli/formatters/json_formatter.rb`
- [GNUplot pipeline](https://github.com/trinistr/dicey/blob/main/lib/dicey/cli/blender.rb): external graph output · Transforms graph-oriented output into PNG via GNUplot. · `lib/dicey/cli/blender.rb`

### Runtime and operations

- [RBS signatures](https://github.com/trinistr/dicey/blob/main/sig/dicey.rbs): API contract · `sig/dicey.rbs`
- [Multi-Ruby CI](https://github.com/trinistr/dicey/blob/main/.github/workflows/CI.yaml): compatibility validation · Validates CRuby, JRuby, and TruffleRuby support. · `.github/workflows/CI.yaml`

## Connections

- Dicey gem API → CLI: exposes command API
- CLI → CLI options: parses
- CLI → DieFoundry: compiles input
- CLI → Calculator runner: calculation mode
- CLI → Roller: roll mode
- DieFoundry → AbstractDie: builds dice
- NumericDie → AbstractDie: specializes
- RegularDie → NumericDie: specializes
- Calculator runner → AutoSelector: selects calculator
- AutoSelector → BaseCalculator: uses contract
- AutoSelector → Distribution algorithms: chooses
- BaseCalculator → AbstractDie: validates inputs
- Distribution algorithms → AbstractDie: calculates distributions
- Roller → AbstractDie: rolls
- Calculator runner → Distribution properties: summarizes distribution
- Calculator runner → CLI formatters: formats result
- Roller → CLI formatters: formats result
- CLI formatters → GNUplot pipeline: graph data
- Dicey gem API → RBS signatures: typed API
- Multi-Ruby CI → Dicey gem API: tests runtimes