# mxgmn/markovjunior architecture

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

- Interactive diagram: https://gitdiagram.com/mxgmn/markovjunior
- Repository: https://github.com/mxgmn/markovjunior

## Overview

##### Project Type and Purpose
- The project is a C#–based interpreter for a probabilistic, grid‐based rewriting language. In essence, it is a domain‐specific language (DSL) that lets you specify programs as sets of rewrite rules—for example, to generate procedural mazes, dungeons, puzzles, or other grid-based simulations.
- The README explains that “MarkovJunior” uses ideas from Markov algorithms, constraint propagation, and even inference (using temperature and heuristics) to “simulate” procedural generation. Therefore, it’s not a full-stack web service, but a self-contained console application that interprets and runs these DSL models.

##### File Structure
- At the project root are intellectual property files (LICENSE, CITATION, FUNDING), a .csproj file (signaling it’s a C# project), and the README.
- The “source” directory contains the core C# code. Key files include:
– Program.cs: the main entry point.
– Interpreter.cs: which likely implements the rule matching, rewrite rule application, and overall probabilistic inference.
– Specific modules like WaveFunctionCollapse.cs, OverlapModel.cs, and Search.cs that target the various rule–matching or constraint propagation strategies.
– Supporting modules (ArrayHelper.cs, XMLHelper.cs, Graphics.cs, GUI.cs) that provide utility functions and rendering/visualization support.
- “models” contains numerous XML files defining various rewriting rule sets (like MazeBacktracker.xml, DungeonGrowth.xml, etc.) which represent the DSL programs for procedural generation.
- “resources” (together with subdirectories for fonts, rules, tilesets, samples, and settings) supplies external assets: a palette file, rule libraries (with *.vox files), and tileset definitions used in visualization and in model execution.
- “images” holds various animated GIFs and snapshots used for documentation and presentation purposes.
- “syntax.md” provides a reference on the language syntax.

##### Main Components and How They Interact (to be reflected
A. Core Engine and Interpreter:
– Program.cs acts as the entry point.
– Interpreter.cs is the heart of the system. It parses the MarkovJunior DSL (the provided XML model files) and manages the execution loop—selecting and applying rewrite rules probabilistically, managing nodes (rulenodes, Markov nodes, sequence nodes) and carrying out constraint propagation (inference).
– Search.cs, OverlapModel.cs, and WaveFunctionCollapse.cs are used for rule matching, conflict resolution, and grid pattern inference.
B. Domain and Data Structures:
– Classes such as Grid.cs, Map.cs, Field.cs, and various Node.cs files provide the grid representation and the node-hierarchy that represents the rewriting rules.
– Rule.cs, RuleNode.cs, and SymmetryHelper.cs embody the rewrite rules’ logic and any symmetry/optimization required per the Boyer–Moore–style pattern matching described.
C. Utilities and Helpers:
– Helper.cs, ArrayHelper.cs, and XMLHelper.cs abstract low-level operations such as searching and XML parsing (necessary for both the models and resources).
– VoxHelper.cs likely handles voxel file processing needed for rendering the 3D models (like converting grid cell content to .vox assets viewable in MagicaVoxel).
D. Asset Management:
– The “models” folder provides input DSL programs that the interpreter will load and execute.
– “resources” and “images” supply supporting assets for visualization, rule samples, and tileset definitions.
– The README and other documentation show how these parts come together for generating visuals.
E. (Optional) Graphical User Interface:
– GUI.cs and Graphics.cs may provide a basic UI (or debugging/visualization) layer for interactive feedback when viewing procedural generation.
F. External Dependencies and Rendering:
– The system outputs generated results (to an “output” directory as mentioned) and supports integration with external tools (like MagicaVoxel using .vox files).

##### Architectural Patterns and Design Principles
- The architecture follows a layered modular design:
– A high-level “control” layer (the interpreter) that directs the rewriting algorithm.
– A lower-level “engine” layer that does pattern matching, rule propagation (caching matches, search via Boyer–Moore) and conducts inference.
– A “data” layer represented by the grid and model definitions (using XML) and supporting resources/assets.
- There is a clear separation between engine logic (in source) and the “configuration” or “model” files (XML in models/ and assets in resources/).
- The use of nested nodes (Markov nodes, sequence nodes, etc.) implies a tree or even state machine–like pattern: the interpreter traverses a node hierarchy to perform rewrites.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine
    subgraph "Core Engine"
        PE["Main Entry (Program.cs)"]:::core
        IE["Interpreter Engine (Interpreter.cs)"]:::core
    end

    %% Rule Matching & Inference Module
    subgraph "Rule Matching & Inference"
        SM["Search (Search.cs)"]:::engine
        WFC["Wave Function Collapse (WaveFunctionCollapse.cs)"]:::engine
        OM["Overlap Model (OverlapModel.cs)"]:::engine
    end

    %% Grid & Node Data Structures
    subgraph "Grid & Node Data Structures"
        GRID["Grid (Grid.cs)"]:::data
        MAP["Map (Map.cs)"]:::data
        NODE["Node (Node.cs)"]:::data
        ONE["OneNode (OneNode.cs)"]:::data
        PN["ParallelNode (ParallelNode.cs)"]:::data
    end

    %% Rule & Rewrite Rule Logic
    subgraph "Rule & Rewrite Rule Logic"
        RULE["Rule (Rule.cs)"]:::logic
        RN["RuleNode (RuleNode.cs)"]:::logic
        SYM["SymmetryHelper (SymmetryHelper.cs)"]:::logic
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        HELP["General Helper (Helper.cs)"]:::util
        AHELP["ArrayHelper (ArrayHelper.cs)"]:::util
        XMLH["XMLHelper (XMLHelper.cs)"]:::util
        VOX["VoxHelper (VoxHelper.cs)"]:::util
    end

    %% DSL Models & Asset Manager
    subgraph "DSL Models & Asset Manager"
        DSL["DSL Models (models/)"]:::asset
        RES["External Assets (resources/)"]:::asset
        IMG["Documentation/Visuals (images/ & syntax.md)"]:::asset
    end

    %% GUI & Rendering
    subgraph "GUI & Rendering"
        GUI["GUI (GUI.cs)"]:::ui
        GRAPH["Graphics (Graphics.cs)"]:::ui
    end

    %% Connections from Core Engine (top) to other modules (vertically)
    PE -->|"initializes"| IE
    IE -->|"calls"| SM
    IE -->|"calls"| WFC
    IE -->|"calls"| OM
    IE -->|"updates"| GRID
    IE -->|"updates"| MAP
    IE -->|"manages"| NODE
    IE -->|"manages"| ONE
    IE -->|"manages"| PN
    IE -->|"applies"| RULE
    IE -->|"applies"| RN
    IE -->|"utilizes"| SYM
    IE -->|"uses"| HELP
    IE -->|"uses"| AHELP
    IE -->|"parses"| XMLH
    IE -->|"processes"| VOX
    IE -->|"loads"| DSL
    IE -->|"loads"| RES
    IE -->|"loads"| IMG
    IE -->|"triggers"| GUI
    IE -->|"triggers"| GRAPH

    %% Styles
    classDef core fill:#cde6f7,stroke:#036,stroke-width:2px;
    classDef engine fill:#f7d6c1,stroke:#a53,stroke-width:2px;
    classDef data fill:#d5f7c1,stroke:#393,stroke-width:2px;
    classDef logic fill:#f7f3c1,stroke:#996,stroke-width:2px;
    classDef util fill:#e2c1f7,stroke:#636,stroke-width:2px;
    classDef asset fill:#c1f7f4,stroke:#36a,stroke-width:2px;
    classDef ui fill:#f7c1c1,stroke:#a33,stroke-width:2px;

    %% Click Events
    click PE "https://github.com/mxgmn/markovjunior/blob/main/source/Program.cs"
    click IE "https://github.com/mxgmn/markovjunior/blob/main/source/Interpreter.cs"
    click SM "https://github.com/mxgmn/markovjunior/blob/main/source/Search.cs"
    click WFC "https://github.com/mxgmn/markovjunior/blob/main/source/WaveFunctionCollapse.cs"
    click OM "https://github.com/mxgmn/markovjunior/blob/main/source/OverlapModel.cs"
    click GRID "https://github.com/mxgmn/markovjunior/blob/main/source/Grid.cs"
    click MAP "https://github.com/mxgmn/markovjunior/blob/main/source/Map.cs"
    click NODE "https://github.com/mxgmn/markovjunior/blob/main/source/Node.cs"
    click ONE "https://github.com/mxgmn/markovjunior/blob/main/source/OneNode.cs"
    click PN "https://github.com/mxgmn/markovjunior/blob/main/source/ParallelNode.cs"
    click RULE "https://github.com/mxgmn/markovjunior/blob/main/source/Rule.cs"
    click RN "https://github.com/mxgmn/markovjunior/blob/main/source/RuleNode.cs"
    click SYM "https://github.com/mxgmn/markovjunior/blob/main/source/SymmetryHelper.cs"
    click HELP "https://github.com/mxgmn/markovjunior/blob/main/source/Helper.cs"
    click AHELP "https://github.com/mxgmn/markovjunior/blob/main/source/ArrayHelper.cs"
    click XMLH "https://github.com/mxgmn/markovjunior/blob/main/source/XMLHelper.cs"
    click VOX "https://github.com/mxgmn/markovjunior/blob/main/source/VoxHelper.cs"
    click DSL "https://github.com/mxgmn/markovjunior/tree/main/models/"
    click RES "https://github.com/mxgmn/markovjunior/tree/main/resources/"
    click IMG "https://github.com/mxgmn/markovjunior/tree/main/images/"
    click GUI "https://github.com/mxgmn/markovjunior/blob/main/source/GUI.cs"
    click GRAPH "https://github.com/mxgmn/markovjunior/blob/main/source/Graphics.cs"
```
