# jlannoo/rollies architecture

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

- Interactive diagram: https://gitdiagram.com/jlannoo/rollies
- Repository: https://github.com/jlannoo/rollies

## Overview

##### Main Components
- User Interface (UI) Components – Represent the visual parts of the application:
- App Component (src/App.tsx) as the entry point.
- UI subcomponents found in the src/components directory: Dialog, Header, Info, Input, Rolls.
- Styling folders (less crucial for architecture but indicate separation of concerns with module.scss files).
- Dice Rolling and Syntax Interpreter Logic – Captures the core functionality:
- Parser Module (src/parser): Contains lexer.ts (tokenizing input), parser.ts (creating a syntax tree), evaluator.ts (calculating roll results), and token.ts (defining tokens).
- Helper functions (src/helpers/loadMD.tsx) which may support rendering markdown (e.g., help texts or instructions).
- Application State Management – Maintains the state of dice roll results or user input:
- Located in src/stores (rolls.ts) which indicates a centralized state store.
- Public Assets – Resources such as images, fonts, and HTML (index.html, resources under public directory):
- These establish the static resources and visual assets (like rollies.png in public/img).
- Tests – Unit tests for the parser components under tests/parser, ensuring the dice syntax processing works correctly.

##### Relationships and Interactions Between Components
- The User interacts with the UI (Input, Dialog, etc.) that is rendered through the App component.
- The Input Component captures the dice expression (e.g., "2d6", "1d20+5").
- The expression is processed by the parser modules: the Lexer tokenizes the input, the Parser builds an abstract syntax tree and the Evaluator computes the dice rolls.
- The computed results are stored using the state management system (rolls.ts in src/stores).
- The result is then displayed via the Rolls component.
- Additionally, the Header and Info components might be used to display instructions or additional contextual information.
- Markdown files under src/md (Long.md, Short.md) are likely used as content resources that can be loaded dynamically via helper functions.

##### Architectural Patterns and Design Principles
- Modular Design – The parser, evaluator, and lexer are separate modules, making it easier to maintain and test (as reflected in the tests directory).
- Component-based Frontend – The React-based UI is neatly split into independent components, each with its own styling.
- Test-Driven Development – Presence of a comprehensive test suite showing a dedication to validation of core components (lexer, parser, evaluator).

##### Relevant Technologies and Frameworks
- TypeScript – Core language to enforce type safety throughout the codebase.
- React – Evidenced by .tsx files in the src directory (App.tsx and various components).
- Vite – Likely used for bundling/building the project (vite.config.js).
- ESLint – For code quality and standard conformance (.eslintrc.cjs).
- GitHub Actions – For CI/CD, as indicated by workflows in .github/workflows.
- SCSS Modules – Used for styling components (e.g., Header.module.scss).

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        app["App Component"]
        dialog["Dialog"]
        header["Header"]
        info["Info"]
        inputComp["Input"]
        rolls["Rolls"]
    end

    %% Logic/Processing Layer
    subgraph "Logic/Processing Layer"
        lexer["Lexer Module"]
        parser["Parser Module"]
        evaluator["Evaluator Module"]
        token["Token Definitions"]
        mdLoader["Markdown Loader Helper"]
    end

    %% State Management
    subgraph "State Management"
        rollsStore["Rolls Store"]
    end

    %% Assets
    subgraph "Assets"
        mdResources["Markdown Content Resources"]
        publicAssets["Public Assets"]
    end

    %% Tests
    subgraph "Tests"
        testParser["Parser Tests"]
    end

    %% Relationships: UI Layer Connections
    app --> dialog
    app --> header
    app --> info
    app --> inputComp
    app --> rolls

    %% Data Flow from UI to Processing to State to Display
    inputComp -->|"tokenize"| lexer
    lexer -->|"buildAST"| parser
    parser -->|"evaluate"| evaluator
    evaluator -->|"resultUpdate"| rollsStore
    rollsStore -->|"display"| rolls

    %% Assets interactions
    publicAssets -->|"resources"| app
    mdResources -->|"loadMarkdown"| mdLoader
    mdLoader -->|"provideContent"| info

    %% Tests validate core logic
    testParser -->|"validate"| lexer
    testParser -->|"validate"| parser
    testParser -->|"validate"| evaluator

    %% Click Events for UI Components
    click app "https://github.com/jlannoo/rollies/blob/master/src/App.tsx"
    click dialog "https://github.com/jlannoo/rollies/blob/master/src/components/Dialog/Dialog.tsx"
    click header "https://github.com/jlannoo/rollies/blob/master/src/components/Header/Header.tsx"
    click info "https://github.com/jlannoo/rollies/blob/master/src/components/Info/Info.tsx"
    click inputComp "https://github.com/jlannoo/rollies/blob/master/src/components/Input/Input.tsx"
    click rolls "https://github.com/jlannoo/rollies/blob/master/src/components/Rolls/Rolls.tsx"

    %% Click Events for Logic/Processing Components
    click lexer "https://github.com/jlannoo/rollies/blob/master/src/parser/lexer.ts"
    click parser "https://github.com/jlannoo/rollies/blob/master/src/parser/parser.ts"
    click evaluator "https://github.com/jlannoo/rollies/blob/master/src/parser/evaluator.ts"
    click token "https://github.com/jlannoo/rollies/blob/master/src/parser/token.ts"
    click mdLoader "https://github.com/jlannoo/rollies/blob/master/src/helpers/loadMD.tsx"

    %% Click Events for State Management
    click rollsStore "https://github.com/jlannoo/rollies/blob/master/src/stores/rolls.ts"

    %% Click Events for Assets
    click mdResources "https://github.com/jlannoo/rollies/tree/master/src/md"
    click publicAssets "https://github.com/jlannoo/rollies/tree/master/public"

    %% Click Events for Tests
    click testParser "https://github.com/jlannoo/rollies/tree/master/tests/parser"

    %% Styles
    classDef ui fill:#CFF09E,stroke:#4CAF50,stroke-width:2px
    classDef logic fill:#F6A55F,stroke:#E65100,stroke-width:2px
    classDef state fill:#A9DEF9,stroke:#0C5460,stroke-width:2px
    classDef assets fill:#FFF3B0,stroke:#FFC107,stroke-width:2px
    classDef tests fill:#F8D7DA,stroke:#721C24,stroke-width:2px

    class app,dialog,header,info,inputComp,rolls ui
    class lexer,parser,evaluator,token,mdLoader logic
    class rollsStore state
    class mdResources,publicAssets assets
    class testParser tests
```
