# rezmason/matrix architecture

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

- Interactive diagram: https://gitdiagram.com/rezmason/matrix
- Repository: https://github.com/rezmason/matrix

## Overview

##### Frontend Components
- **HTML/CSS (`index.html`)**: The entry point rendering the canvas and UI elements.
- **JavaScript (`js/` Directory)**:
- **Core Scripts (`main.js`, `config.js`)**: Manage application logic and configurations.
- **Rendering Modules (`regl/`, `webgpu/`)**: Handle graphics rendering through REGL (WebGL) and WebGPU.
- **Libraries (`lib/` Directory)**:
- **`gl-matrix.js`**: Matrix and vector operations for transformations.
- **`gpu-buffer.js`**: Management of GPU buffers.
- **`holoplaycore.module.js`**: Potential integration with Holoplay or similar technologies.
- **Shaders (`shaders/` Directory)**:
- **GLSL Shaders (`glsl/`)**: For WebGL rendering.
- **WGSL Shaders (`wgsl/`)**: For WebGPU rendering.

##### Assets and Resources
- **`assets/`**: Contains command scripts and other necessary assets.
- **`svg sources/`**: SVG files for glyphs and graphics.
- **`glyph order.txt` & `msdfgen/`**: Manage glyph ordering and distance field generation.

##### Platform-Specific Extensions (`playdate/` Directory)
- **C and Lua Implementations**: Extensions or tools for specific platforms or functionalities.

##### Configuration and Documentation
- **`README.md`**, **`TODO.txt`**, **`INSTRUCTIONS.md`**: Documentation and project guidelines.
- **Configuration Files**: `.gitmodules`, `CMakeLists.txt`

##### b. Relationships and Interactions

- **User Interaction Flow:**
1. Users access the application via `index.html`, which loads necessary CSS and JavaScript files.
2. JavaScript initializes the rendering context using REGL or WebGPU based on browser capabilities.
3. Shaders from the `shaders/` directory are compiled and linked to handle visual effects.
4. Assets and SVGs are loaded and processed for glyph rendering.
5. User customization via URL parameters alters configurations dynamically, affecting rendering pipelines.

- **Module Interactions:**
- **Core Scripts** interact with **Rendering Modules** to manage graphics.
- **Libraries** provide essential functionalities to both **Core Scripts** and **Rendering Modules**.
- **Shaders** are utilized by **Rendering Modules** to execute GPU-accelerated effects.
- **Platform-Specific Extensions** interact with core components to offer additional functionalities or integrations.

##### c. Architectural Patterns and Design Principles

- **Modular Architecture:** Clear separation of concerns through distinct directories for JS modules, shaders, and platform-specific code.
- **Abstraction Layers:** Use of REGL abstracts WebGL complexities, allowing for cleaner code and easier maintenance.
- **GPU-Accelerated Rendering:** Leveraging WebGL and WebGPU for performant graphics rendering.
- **Extensibility:** Platform-specific directories indicate readiness for extensions and integrations.
- **Customization and Configuration:** URL-based customization promotes flexibility and user-driven configurations.

##### d. Relevant Technologies, Frameworks, or Libraries

- **Web Technologies:** HTML5, CSS3, JavaScript (ES6+)
- **Graphics APIs:** WebGL (via REGL), WebGPU (beta support)
- **Rendering Libraries:** REGL for WebGL abstraction
- **Shader Languages:** GLSL for WebGL, WGSL for WebGPU
- **Utility Libraries:** `gl-matrix.js`, `gpu-buffer.js`
- **Build Tools:** CMake for C projects in `playdate/`
- **Version Control:** Git (indicated by `.gitmodules`)

##### Elements

- **Clear Labels:** Each component (e.g., HTML/CSS, JavaScript Core, REGL Module, WebGPU Module, Shaders, Libraries) should be distinctly labeled.
- **Libraries and Utilities:** Distinctive styling to differentiate from core components.
- **Shaders:** Perhaps a unique pattern or border to signify their role in GPU processing.

##### Detailed Architectural Elements to Capture

- **Initialization Flow:** How the application initializes, choosing between REGL and WebGPU based on browser support.
- **Shader Compilation:** The process of loading and compiling shaders from the respective directories.
- **Rendering Pipeline:** Step-by-step rendering process, including asset loading, glyph processing, and effect rendering.
- **Customization Parameters:** How URL parameters feed into the configuration and influence the rendering logic.
- **Platform-Specific Integrations:** Showing how the `playdate` extensions interface with the core application.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities

    %% Subgraphs and modules
    subgraph Frontend
        HTML["HTML/CSS Frontend"]:::frontend
    end

    subgraph "Core JavaScript"
        mainJS["main.js"]:::core
        configJS["config.js"]:::core
    end

    subgraph "Rendering Modules"
        regl["REGL Rendering Modules (WebGL)"]:::rendering
        webgpu["WebGPU Rendering Modules"]:::rendering
    end

    subgraph Libraries
        lib["Libraries"]:::libraries
    end

    subgraph Shaders
        glsl["GLSL Shaders"]:::shaders
        wgsl["WGSL Shaders"]:::shaders
    end

    subgraph Assets
        assets["Assets"]:::assets
        svg["SVG Sources"]:::assets
        msdf["MSDF Generation"]:::assets
    end

    subgraph "Platform Extensions"
        playdate["Platform-Specific Extensions"]:::platform
    end

    %% Connections
    HTML --> mainJS
    HTML --> configJS

    mainJS -->|"uses"| lib
    configJS -->|"uses"| lib

    mainJS -->|"initializes"| regl
    mainJS -->|"initializes"| webgpu

    regl -->|"uses"| glsl
    webgpu -->|"uses"| wgsl

    regl --> assets
    regl --> svg
    regl --> msdf

    webgpu --> assets
    webgpu --> svg
    webgpu --> msdf

    playdate --> mainJS

    %% Click Events
    click HTML "https://github.com/rezmason/matrix/blob/master/index.html"
    click mainJS "https://github.com/rezmason/matrix/blob/master/js/main.js"
    click configJS "https://github.com/rezmason/matrix/blob/master/js/config.js"
    click regl "https://github.com/rezmason/matrix/tree/master/js/regl/"
    click webgpu "https://github.com/rezmason/matrix/tree/master/js/webgpu/"
    click lib "https://github.com/rezmason/matrix/tree/master/lib/"
    click glsl "https://github.com/rezmason/matrix/tree/master/shaders/glsl/"
    click wgsl "https://github.com/rezmason/matrix/tree/master/shaders/wgsl/"
    click assets "https://github.com/rezmason/matrix/tree/master/assets/"
    click svg "https://github.com/rezmason/matrix/tree/master/svg sources/"
    click msdf "https://github.com/rezmason/matrix/tree/master/msdfgen/"
    click playdate "https://github.com/rezmason/matrix/tree/master/playdate/"

    %% Styles
    classDef frontend fill:#1f77b4,stroke:#333,stroke-width:2px;
    classDef core fill:#2ca02c,stroke:#333,stroke-width:2px;
    classDef rendering fill:#ff7f0e,stroke:#333,stroke-width:2px;
    classDef libraries fill:#98df8a,stroke:#333,stroke-width:2px;
    classDef shaders fill:#ffbb78,stroke:#333,stroke-width:2px;
    classDef assets fill:#9467bd,stroke:#333,stroke-width:2px;
    classDef platform fill:#c7c7c7,stroke:#333,stroke-width:2px;

    class HTML frontend
    class mainJS,configJS core
    class regl,webgpu rendering
    class lib libraries
    class glsl,wgsl shaders
    class assets,svg,msdf assets
    class playdate platform
```
