# randsum/randsum-ts architecture

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

- Interactive diagram: https://gitdiagram.com/randsum/randsum-ts
- Repository: https://github.com/randsum/randsum-ts

## Overview

##### Main Components

a. Core Components:
- Dice Engine (src/dice)
- Custom Faces Handler (src/faces)
- Notation Parser (src/notation)
- Roll Tower (src/tower)
- Utilities (src/utils)

**Top Layer: Public API**

**Middle Layer: Core Processing**

**Bottom Layer: Utility Services**

##### Component Relationships

a. Public API Layer:
- Main entry points: `roll()` function and `D` class
- To the notation parser for string inputs
- To the dice engine for direct numeric/configuration inputs

b. Core Processing Layer:
- Notation Parser: Show how it processes dice notation strings
- Dice Engine: Illustrate dice creation and basic rolling
- Custom Faces Handler: Show custom dice face processing
- Roll Tower: Demonstrate roll execution and modifier application

c. Utility Layer:
- Configuration Processors
- Random Number Generation
- Result Formatters
- Type Guards and Validators

##### Specific Implementation Details

Key features:
- How the dice notation parser ('4d6L') flows through the system
- Custom faces feature (['heads', 'tails'])
- Demonstrate modifier application flow (drop lowest, etc.)
- Validation pathways

##### Flow Directions

- Input flow from API to core components
- Data transformation between components
- Result aggregation and return paths

##### Type safety and validation paths

- All component types
- Special symbols used

This system design should help developers understand how randsum processes both simple rolls like `roll(20)` and complex operations like `roll('4d6L')` through its various components while maintaining type safety and flexibility.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Public API Layer"
        API["Public API Entry Points"]
        D["D Class"]
        RF["Roll Function"]
    end

    subgraph "Core Processing Layer"
        NP["Notation Parser"]
        DE["Dice Engine"]
        CF["Custom Faces Handler"]
        RT["Roll Tower"]
    end

    subgraph "Utility Layer"
        CP["Configuration Processors"]
        RNG["Random Number Generation"]
        RF2["Result Formatters"]
        TG["Type Guards & Validators"]
    end

    %% Connections from Public API to Core
    API --> NP
    API --> DE
    D --> DE
    RF --> DE

    %% Core Processing Connections
    NP --> DE
    DE --> CF
    DE --> RT
    CF --> RT

    %% Utility Connections
    RT --> RNG
    NP --> TG
    DE --> CP
    RT --> RF2

    %% Click Events
    click API "https://github.com/randsum/randsum-ts/blob/main/src/index.ts"
    click D "https://github.com/randsum/randsum-ts/blob/main/src/dice/D.ts"
    click RF "https://github.com/randsum/randsum-ts/blob/main/src/dice/dice.ts"
    click NP "https://github.com/randsum/randsum-ts/tree/main/src/notation"
    click DE "https://github.com/randsum/randsum-ts/tree/main/src/dice"
    click CF "https://github.com/randsum/randsum-ts/tree/main/src/faces"
    click RT "https://github.com/randsum/randsum-ts/tree/main/src/tower"
    click CP "https://github.com/randsum/randsum-ts/blob/main/src/utils/argumentToRollConfig.ts"
    click RNG "https://github.com/randsum/randsum-ts/blob/main/src/utils/coreRandom.ts"
    click RF2 "https://github.com/randsum/randsum-ts/tree/main/src/utils/configToDescription"
    click TG "https://github.com/randsum/randsum-ts/blob/main/src/notation/guards.ts"

    %% Styling
    classDef api fill:#2374ab
    classDef core fill:#57a773
    classDef utility fill:#ffc857
    classDef critical fill:#ed474a
    
    class API,D,RF api
    class NP,DE,CF,RT core
    class CP,RNG,RF2,TG utility

    %% Legend
    subgraph Legend
        L1["API Components"]:::api
        L2["Core Components"]:::core
        L3["Utility Components"]:::utility
    end
```
