# kunalb2003/rubiks-cube-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/kunalb2003/rubiks-cube-simulator
- Repository: https://github.com/kunalb2003/rubiks-cube-simulator

## Overview

##### Main Components
a. Simulation Engine and Core Loop:
- Files: src/Engine.java, src/Run.java
- Responsible for initializing the application, maintaining the game loop, and coordinating updates.
b. Cube Logic and Data Model:
- Files: src/cube/*.java (Cube.java, Cubie.java, Face.java, Move.java, Scramble.java) and the solver in src/cube/solver (Solver.java, Node.java).
- Manages the internal representation of the Rubik’s Cube, applying moves, and calculating the solution.
c. Rendering and Graphics:
- Files: src/graphics/* (Camera.java, Shader.java, Mesh.java, Quad.java, Transform.java, etc.), src/display/Window.java, shaders directory for vertex (basic.vs) and fragment (basic.fs) shaders.
- Handles the OpenGL rendering pipeline and drawing of the cube with proper transformations.
d. Input and Transform Controllers:
- Files: src/graphics/transform/controller/* (PositionController.java, RotationController.java)
- Manages user interactions and object transformations.
e. Cube State Tool (Web-based Component):
- Files: cube-state-tool/anna.html and cube-state-tool/anna.js
- Likely offers a browser-based interface for visualizing cube states or debugging.
f. External Libraries and Dependencies:
- Directories: lib/joml and lib/lwjgl (with its subcomponents for OpenGL, GLFW, stb, and Assimp).
- Provides the underlying graphics, math, and native bindings used by the application.

##### Relationships and Interactions
- The Simulation Engine (Engine.java/Run.java) sits at the center, initializing all subsystems.
- It instantiates the Cube Logic (cube data model and solver) to manage the cube’s state and algorithms.
- The Engine interfaces with the Rendering/Graphics module and Display (Window.java) to show the cube and other visual elements.
- Input from the user is received (possibly via controllers or window callbacks) and then propagated to update cube transformations.
- The shader files in the shaders folder are applied during rendering, hinting at a pipeline where Shader (Shader.java) objects are prepared and used.
- The web-based cube-state-tool might integrate with simulation outputs or be used as an independent demonstration of state management.

##### Architectural Patterns or Principles
- Game Loop / Engine Pattern: Central loop managing update, render, and input.
- Separation of Concerns: Dividing the cube’s logic (model and solver), rendering, and user input into distinct modules.
- Use of External Libraries: LWJGL handles cross-platform graphics (OpenGL, GLFW), while JOML provides math utilities.
- Modularity: The directory structure (separate packages for cube, solver, graphics, display, and transformation controllers) shows a clean separation that eases maintenance and testing.

##### Recommendations
- Engine / Main Loop
- Cube Model & Logic (including solver)
- Rendering / Graphics (include sub-components like Camera, Shader, and Scene management)
- / Window management
- Input & Transformation Controller
- Cube-State Tool (Web Interface)
- External Libraries (LWJGL and JOML)
- How the Engine initiates rendering by calling on the Display module.
- Data flow from the Cube Logic to the Rendering component.
- Optionally, a distinct style for external dependencies.
- Component’s responsibilities are noted (e.g., “Cube Solver – computes solution moves based on the current state”).
e. Integration points:
- How the web-based cube-state-tool might be integrated or used as an independent tool for demonstration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine Subgraph
    subgraph "Core Engine"
        A1["Engine (Core)"]:::core
        A2["Run (Core Loop)"]:::core
        A1 -->|"starts"| A2
    end

    %% Cube Logic Subgraph
    subgraph "Cube Logic"
        B1["Cube Model & Data"]:::model
        B2["Cube Solver"]:::model
        B1 -->|"calculates"| B2
    end

    %% Graphics & Display Subgraph
    subgraph "Graphics & Display"
        C1["Graphics Engine"]:::render
        C2["Display (Window)"]:::render
        C3["Shaders (Basic)"]:::render
        C1 -->|"renders"| C2
        C1 -->|"applies"| C3
    end

    %% Input Controllers Subgraph
    subgraph "Input Layer"
        D["Input & Transform Controllers"]:::input
    end

    %% Web-based Component Subgraph
    subgraph "Web Interface"
        E["Cube-State Tool (Web)"]:::web
    end

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        F1["LWJGL"]:::external
        F2["JOML"]:::external
    end

    %% Interconnections between subgraphs
    A2 -->|"updates"| B1
    A2 -->|"rendersWith"| C1
    A2 -->|"captures"| D
    D -->|"modifies"| B1
    B1 -->|"providesState"| C1
    B1 -->|"exportsState"| E
    F1 -->|"supports"| A1
    F1 -->|"supports"| C1
    F2 -->|"supports"| B1
    F2 -->|"supports"| C1

    %% Click Events
    click A1 "https://github.com/kunalb2003/rubiks-cube-simulator/blob/main/src/Engine.java"
    click A2 "https://github.com/kunalb2003/rubiks-cube-simulator/blob/main/src/Run.java"
    click B1 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/src/cube/"
    click B2 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/src/cube/solver/"
    click C1 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/src/graphics/"
    click C2 "https://github.com/kunalb2003/rubiks-cube-simulator/blob/main/src/display/Window.java"
    click C3 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/shaders/basic/"
    click D "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/src/graphics/transform/controller/"
    click E "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/cube-state-tool/"
    click F1 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/lib/lwjgl/"
    click F2 "https://github.com/kunalb2003/rubiks-cube-simulator/tree/main/lib/joml/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef model fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef render fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef input fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef web fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef external fill:#F0E68C,stroke:#000,stroke-width:2px;
```
