# matecomputazionale/matecomp architecture

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

- Interactive diagram: https://gitdiagram.com/matecomputazionale/matecomp
- Repository: https://github.com/matecomputazionale/matecomp

## Overview

##### Project type and purpose
- This is a standalone Mathematica–based interactive board‐game application.
- It consists of a front-end Notebook UI (.nb) that ties together a set of .m packages implementing:
- The game board (Board.m)
- The die and random seed logic (Dice.m)
- Euclidean‐gcd logic (Euclide.m, IDivisori.m)
- UI buttons & user actions (Buttons.m, Aiuto.m, Suggerimento.m)
- Image assets (Images/)
- The README clarifies that the user rolls a die to move a pawn, solves a gcd in n steps, can restart at any time, ask for hints, and clear fields.

##### File structure
- Top-level .m modules each encapsulate a distinct domain:
- Board.m → game state & rendering
- Dice.m → roll logic & seeding
- Euclide.m / IDivisori.m → mathematics of gcd and divisors
- Buttons.m → definitions of all interactive UI controls
- Aiuto.m / Suggerimento.m → “help” and “hint” routines
- IDivisori.nb is presumably the development notebook for divisors logic.
- Images/ holds UI or board graphics.
- README.md contains specifications and future tasks (removing paths, red code, documentation sections).

##### README for additional insights
- Emphasis on: restart functionality, help & suggestion buttons, gcd prompt (quotient & remainder), dynamic board resizing based on seed.

a. Main components to represent:
1. Mathematica Front‐End Notebook (UI Layer)
2. Controller layer (Buttons.m, Aiuto.m, Suggerimento.m)
3. Model / Game State (Board.m, variables holding pawn position, board configuration, seed)
4. Math Engine (Dice.m for RNG; Euclide.m + IDivisori.m for gcd/divisors)
5. Assets (Images folder)
b. Relationships & interactions:
– UI Layer loads all .m packages into the Mathematica Kernel.
– User clicks a Button → Buttons.m dispatches a function call to the Kernel.
– The Kernel manipulates the Model (Board state) or invokes the Math Engine.
– Results flow back to the UI: updated board graphic, prompt for gcd, hints, cleared fields.
– Image assets are read by Board.m or Buttons.m to render the UI.
c. Architectural patterns & principles:
– MVC‐style separation:
- View = Notebook front‐end (cells, Graphics, Controls)
- Controller = Buttons.m and helper modules mapping UI events to function calls
- Model = Board state variables, seed, pawn position
- Domain logic = Dice, Euclide, IDivisori
– Single‐process architecture: everything runs in one Mathematica Kernel.
– Modular .m files to isolate functionality and ease testing.
d. Key technologies & libraries:
– Wolfram Language / Mathematica front‐end & kernel
– Built-in Controls: Button, Manipulate, Graphics
– Custom .m packages for domain logic

##### Capturing essential architectural elements
- Initialization: Notebook loading all packages
- Core user interactions: roll, move, solve gcd, restart, help, clear
- How the game state evolves and is rendered
- Use of external assets (Images)
- This approach splits the project into distinct components, making dependencies and flows crystal-clear.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraphs for layers
    subgraph "UI Layer"
        UI["IDivisori.nb: Notebook UI"]:::view
    end

    subgraph "Controller Layer"
        Btn["Buttons.m: UI Event Handlers"]:::controller
        Help["Aiuto.m: Help Module"]:::controller
        Hint["Suggerimento.m: Hint Module"]:::controller
    end

    subgraph "Model Layer"
        Board["Board.m: Game State & Rendering"]:::model
    end

    subgraph "Math Engine"
        Dice["Dice.m: RNG & Die Logic"]:::engine
        Euclid["Euclide.m: Euclidean GCD"]:::engine
        Divi["IDivisori.m: Divisors Utility"]:::engine
    end

    subgraph "Assets"
        Img["Images/: Image Assets"]:::assets
    end

    %% Data flows and interactions
    UI -->|"loads handlers"| Btn
    UI -->|"loads help module"| Help
    UI -->|"loads hint module"| Hint

    Btn -->|"roll or move"| Dice
    Btn -->|"update game state"| Board
    Dice -->|"random value"| Board
    Board -->|"render graphics"| UI
    Board -->|"use images"| Img

    Help -->|"compute assistance"| Euclid
    Hint -->|"compute hint"| Euclid
    Euclid -->|"fetch divisors"| Divi
    Euclid -->|"return steps"| UI

    %% Click events
    click UI "https://github.com/matecomputazionale/matecomp/blob/main/IDivisori.nb"
    click Btn "https://github.com/matecomputazionale/matecomp/blob/main/Buttons.m"
    click Help "https://github.com/matecomputazionale/matecomp/blob/main/Aiuto.m"
    click Hint "https://github.com/matecomputazionale/matecomp/blob/main/Suggerimento.m"
    click Board "https://github.com/matecomputazionale/matecomp/blob/main/Board.m"
    click Dice "https://github.com/matecomputazionale/matecomp/blob/main/Dice.m"
    click Euclid "https://github.com/matecomputazionale/matecomp/blob/main/Euclide.m"
    click Divi "https://github.com/matecomputazionale/matecomp/blob/main/IDivisori.m"
    click Img "https://github.com/matecomputazionale/matecomp/tree/main/Images/"

    %% Styles
    classDef view fill:#cceaff,stroke:#333,stroke-width:1px
    classDef controller fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef model fill:#ffff99,stroke:#333,stroke-width:1px
    classDef engine fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef assets fill:#dddddd,stroke:#333,stroke-width:1px
```
