# felcardoso/highdice architecture

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

- Interactive diagram: https://gitdiagram.com/felcardoso/highdice
- Repository: https://github.com/felcardoso/highdice

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **static, single-page browser game** (HTML/CSS/vanilla JS) that runs entirely on the client. There is **no backend**, **no database**, and no network API layer. The “system” is therefore the **browser runtime + UI + game engine/state + rendering/events**, optionally packaged as a **PWA** via the web manifest.

Primary purpose: implement a **single-player, poker-like dice game loop** (roll/select/reroll/play/score/upgrade/reset) with stateful progression (stake, levels, hand upgrades) and UI updates.

##### File-structure-driven architecture (how the repo maps to components)
From the tree:

- `index.html`
The **UI shell**: DOM structure, buttons, dice area, HUD, log console, modal(s) for upgrades.
- `css/styles.css`
Pure **presentation layer** (layout, styling, responsive, visual states like “selected die”).
- `js/game.js`
The **entire application logic**: state model, rules, scoring, rendering functions, DOM event handlers.
- `assets/site.webmanifest`
- `release/v1.0A.md`

**DOM/UI → event handlers → game engine/state → scoring/evaluation → render/update DOM**.

##### README-derived “key runtime symbols” (what to highlight)
`js/game.js` contains the core modules/classes and major flows:

- Core classes (domain model / state):
- `Dice` — represents individual die state/value/selection.
- `Table` — evaluates hands and likely holds dice/hand evaluation logic.
- `Run` — orchestrates a “run” / progression loop (stake, plays, rerolls, level-up).
- `Player` — player progression, hand levels/upgrades, resources.

- Constants (rules configuration):
- `HAND_SCORE`, `HAND_NAMES`, `HAND_ORDER` — scoring tables and ordering.

- Rendering/UI functions:
- `renderHUD`, `renderDice` — translate current state into DOM.

- Actions / controllers:
- `rerollSelected`, `playOnce`, `openUpgradeModal`, `resetGame` — user-triggered operations that mutate state then trigger re-render/logging.

##### UI/DOM Layer (`index.html`)
- Dice display area
- HUD (stake/plays/rerolls/level)
- Controls (Reroll, Play Hand, Hand Upgrade, Reset)
- Console log
- Upgrade modal

##### Event Handling / Controller (in `game.js`)
- Click die (toggle select)
- Click reroll (`rerollSelected`)
- Click play (`playOnce`)
- Click upgrade (`openUpgradeModal`)
- Click reset (`resetGame`)

##### Game State / Domain Model (in `game.js`)
- `Run` (game loop/progression; stake depletion → level up)
- `Player` (hand levels, upgrades)
- `Dice` (values, selected flags)
- `Table` (hand evaluation methods; “rules engine”)

##### Rules & Scoring Configuration (in `game.js`)
- `HAND_SCORE`, `HAND_ORDER`, `HAND_NAMES`

##### Rendering (in `game.js`)
- `renderDice` (state → dice DOM)
- `renderHUD` (state → HUD DOM)
- (If present) log rendering / append-to-console

##### PWA Manifest (`assets/site.webmanifest`)
- Relationship to browser install prompt (no runtime logic, but include as packaging)

- **User → UI/DOM** (clicks)
- **UI/DOM → Controller actions** (event listeners call functions)
- **Controller actions → Game State** (mutations: reroll changes dice values; playOnce updates stake, plays; upgrades modify player hand levels)
- **Controller actions → Table (hand evaluation)** (compute hand type, apply `HAND_SCORE`)
- **Controller actions → Rules constants** (read scoring tables)
- **Controller actions → Rendering** (after state change, call `renderHUD`/`renderDice`, update log)
- **Rendering → UI/DOM** (DOM updates)

##### Architectural patterns/design principles present

- **Domain model vs. rendering**: stateful classes (`Run/Player/Table/Dice`) vs `render*` functions.
- **Controller/action functions** as the boundary between UI events and state mutation.
- **Configuration-driven scoring**: scoring tables (`HAND_SCORE`) as declarative rule configuration.
- **Single-threaded event loop**: everything runs in the browser JS runtime; no concurrency model besides standard event callbacks.

##### Relevant technologies
- HTML5 + CSS3 + Vanilla JavaScript
- Browser DOM APIs
- PWA manifest (install metadata)

##### `renderHUD()`, `renderDice()`, append log

To maximize clarity:

- **Clear labels**:
- Use concrete names: `renderHUD`, `renderDice`, `rerollSelected`, `playOnce`, `Run`, `Player`, `Table`, `Dice`, `HAND_SCORE`.
- Blue rectangles: UI/DOM components
- Green rectangles: Domain model/state (`Run/Player/Dice/Table`)
- Orange rectangles: Controllers/actions (`playOnce`, `rerollSelected`, etc.)
- Gray rectangles: Config/constants (`HAND_SCORE`)
- Purple rectangle: Rendering functions

##### Practical “don’t overthink it” decomposition (recommended final component list)

- UI Shell (`index.html`)
- Styles (`css/styles.css`)
- Controllers:
- `rerollSelected`
- `playOnce`
- `openUpgradeModal`
- `resetGame`
- “die click handler” (toggle select)
- Rendering:
- `renderHUD`
- `renderDice`
- “log renderer” (if present)
- Domain Model:
- `Run`
- `Player`
- `Table`
- `Dice`
- Rules/Config:
- `HAND_SCORE`
- `HAND_NAMES`
- `HAND_ORDER`
- PWA:
- `assets/site.webmanifest`
- Hosting/Execution Environment:
- Browser JS runtime / DOM
- (Optional) GitHub Pages static hosting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ===== Context / Container =====
    U["User"]:::external

    subgraph "Execution Environment"
        B["Browser (HTML5/CSS3/Vanilla JS)\nDOM + JS Event Loop"]:::platform
        H["Static Hosting\n(GitHub Pages / Local File)"]:::external
    end

    H -->|"serves_static_assets"| B
    U -->|"clicks/taps"| B

    %% ===== SPA Components (Client-only) =====
    subgraph "High Dice SPA (Client-only)"
        direction TB

        subgraph "UI / DOM Layer"
            direction TB
            UI["UI Shell\n(Dice area, HUD, Controls, Log, Upgrade Modal)"]:::ui
        end

        subgraph "Presentation"
            direction TB
            CSS["Stylesheet\n(Layout, Responsive, Selected-Die State)"]:::cssStyle
        end

        subgraph "Application Logic (Single JS Bundle)"
            direction TB

            subgraph "Event Handling / Controllers"
                direction TB
                DieClick["Die Click Handler\n(toggle select)"]:::controller
                Reroll["rerollSelected()"]:::controller
                Play["playOnce()"]:::controller
                Upgrade["openUpgradeModal()"]:::controller
                Reset["resetGame()"]:::controller
            end

            subgraph "Rendering"
                direction TB
                RenderHUD["renderHUD()"]:::render
                RenderDice["renderDice()"]:::render
                LogRender["Log Renderer\n(append/update console)"]:::render
            end

            subgraph "Game State / Domain Model"
                direction TB
                Run["Run (progression/game loop)"]:::domain
                Player["Player (upgrades/resources)"]:::domain
                Table["Table (hand evaluation)"]:::domain
                Dice["Dice (value + selected flag)"]:::domain
            end

            subgraph "Rules & Scoring (Configuration)"
                direction TB
                HandOrder["HAND_ORDER"]:::config
                HandNames["HAND_NAMES"]:::config
                HandScore["HAND_SCORE"]:::config
            end
        end

        subgraph "Packaging (PWA)"
            direction TB
            Manifest["Web Manifest\n(install metadata)"]:::package
        end

        subgraph "Documentation (Non-runtime)"
            direction TB
            Readme["README (project overview)"]:::doc
            ReleaseNotes["Release Notes (v1.0A)"]:::doc
        end
    end

    %% ===== Relationships / Flows =====
    B -->|"loads_html"| UI
    B -->|"loads_css"| CSS
    B -->|"loads_js"| DieClick

    CSS -.->|"styles"| UI

    Manifest -.->|"install_metadata"| B

    %% UI events -> controllers
    UI -->|"click_die"| DieClick
    UI -->|"click_reroll"| Reroll
    UI -->|"click_play_hand"| Play
    UI -->|"click_upgrade"| Upgrade
    UI -->|"click_reset"| Reset

    %% Controllers -> domain mutations / orchestration
    DieClick -->|"toggle_selected"| Dice
    Reroll -->|"mutate_values(selected)"| Dice
    Play -->|"consume_play/update_stake"| Run
    Play -->|"update_progression"| Player
    Upgrade -->|"apply_hand_upgrade"| Player
    Reset -->|"reinitialize"| Run
    Reset -->|"reinitialize"| Player
    Reset -->|"reset_dice"| Dice

    %% Hand evaluation + scoring tables
    Play -->|"evaluate_hand(dice)"| Table
    Table -.->|"reads"| HandOrder
    Table -.->|"reads"| HandNames
    Table -.->|"reads"| HandScore
    Play -.->|"lookup_score"| HandScore

    %% Render cycle after actions
    DieClick -->|"request_render"| RenderDice
    Reroll -->|"request_render"| RenderDice
    Play -->|"request_render"| RenderHUD
    Play -->|"request_render"| RenderDice
    Play -->|"append_log"| LogRender
    Upgrade -->|"request_render"| RenderHUD
    Upgrade -->|"append_log"| LogRender
    Reset -->|"request_render"| RenderHUD
    Reset -->|"request_render"| RenderDice
    Reset -->|"append_log"| LogRender

    %% Rendering -> DOM updates
    RenderHUD -->|"update_dom"| UI
    RenderDice -->|"update_dom"| UI
    LogRender -->|"update_dom"| UI

    %% Domain interactions
    Run -->|"owns/uses"| Player
    Run -->|"owns/uses"| Dice
    Table -->|"inspects"| Dice

    %% ===== Click Events (mapped paths only) =====
    click UI "https://github.com/felcardoso/highdice/blob/main/index.html"
    click CSS "https://github.com/felcardoso/highdice/blob/main/css/styles.css"
    click DieClick "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Reroll "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Play "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Upgrade "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Reset "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click RenderHUD "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click RenderDice "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Run "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Player "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Table "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Dice "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click HandScore "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click HandNames "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click HandOrder "https://github.com/felcardoso/highdice/blob/main/js/game.js"
    click Manifest "https://github.com/felcardoso/highdice/blob/main/assets/site.webmanifest"
    click ReleaseNotes "https://github.com/felcardoso/highdice/blob/main/release/v1.0A.md"
    click Readme "https://github.com/felcardoso/highdice/blob/main/README.md"

    %% ===== Styles =====
    classDef external fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#111827
    classDef platform fill:#111827,stroke:#0ea5e9,stroke-width:1px,color:#f9fafb
    classDef ui fill:#dbeafe,stroke:#2563eb,stroke-width:1px,color:#0f172a
    classDef cssStyle fill:#e0f2fe,stroke:#0284c7,stroke-width:1px,color:#0f172a,stroke-dasharray: 4 3
    classDef controller fill:#ffedd5,stroke:#f97316,stroke-width:1px,color:#7c2d12
    classDef domain fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
    classDef config fill:#e5e7eb,stroke:#6b7280,stroke-width:1px,color:#111827
    classDef render fill:#ede9fe,stroke:#7c3aed,stroke-width:1px,color:#1f1147
    classDef package fill:#f5d0fe,stroke:#a21caf,stroke-width:1px,color:#3b0764,stroke-dasharray: 4 3
    classDef doc fill:#fff7ed,stroke:#9a3412,stroke-width:1px,color:#431407,stroke-dasharray: 4 3
```
