# yuu6883/markovjuniorweb architecture

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

- Interactive diagram: https://gitdiagram.com/yuu6883/markovjuniorweb
- Repository: https://github.com/yuu6883/markovjuniorweb

## Overview

##### Project type and purpose
- This is a full-stack TypeScript port of the MarkovJunior procedural content generator.
- It runs in the browser (React/TSX frontend), in Node.js (CLI), and optionally via WebAssembly for performance-critical algorithms.
- It loads XML model definitions and voxel rules, executes a Wave Function Collapse-style interpreter, and renders or exports `.vox` files.

##### File structure
- src/
- core engine modules:
– src/interpreter.ts, src/search.ts, src/rule.ts
– src/mj-nodes/* → implementation of node types (map, convolution, parallel, wfc, etc.)
– src/helpers/* → data structures, I/O readers/writers, symmetry, voxel utilities
- loader: src/loader/index.ts → XML model & rule file parser
- render: src/render/* → abstract/bitmap/isometric/pathtrace renderers, WebGL helper library
- wasm: src/wasm/* → high-performance tasks in WebAssembly (search, observe, optimization) + worker
- native: src/native/* → C headers & compile script producing .wasm for core algorithms
- node: src/node/* → CLI program adapter for Node.js
- web: src/web/* → React components (center/left/right/mobile), state management, index.tsx, HTML template, CSS
- static/
- static/models.xml, static/models/*.xml → model definitions
- static/resources/{palette, rules, samples, tilesets} → assets fed to loader
- Config/build files: webpack.config.js, tsconfig.json, package.json, .github workflows

##### README for additional insights
- Confirms browser & Node.js targets; heavy computation can be offloaded to WebAssembly.
- Highlights optional “JIT” AssemblyScript → Wasm optimization branch.
- Emphasizes features: isometric rendering, .vox export, node tree visualization.

##### Main components & interactions
a. Core Engine
- Loader: parses XML models & rules → produces internal graph/rule structures
- Interpreter & Search: executes MarkovJunior algorithm with mj-nodes, helper data structures
- Rule Engine: applies voxel rules, symmetry, pattern constraints
b. WebAssembly Subsystem
- Native C code compiled to .wasm (via compile.sh)
- AssemblyScript “JIT” version (optional optimization branch)
- Wasm modules loaded by src/wasm/index.ts, executed in a WebWorker (src/wasm/worker.ts)
c. Presentation Layer
- Browser UI: React components in src/web render controls & 2D/3D outputs
- Render Engine: WebGL helper lib for isometric/bitmap/pathtrace rendering
- CLI: Node adapter writes `.vox` files to output directory (src/node/program.ts)
d. Static Asset Server
- Serves static/models, static/resources via webpack dev server or static site build

##### Relationships & data flows
- User action (UI or CLI) → Loader loads XML → Interpreter invokes Search + Rule modules (possibly via Wasm worker) → produces grid/voxel output → Render Engine visualizes in browser or Writer serializes `.vox` → Completed result shown or saved
- UI → Core Engine inputs
- Core Engine ↔ Wasm Worker boundary
- Core Engine → Render Engine or Writer
- Static Asset Store → Loader

##### Architectural patterns & design principles
- Modular separation: Loader / Core / Presentation / WASM / CLI
- Pluggable node graph (mj-nodes directory implements Strategy pattern for each node type)
- Asynchronous boundary: WebWorker / Wasm offloading for CPU-intensive tasks
- Single-page app served by webpack, with dev/prod workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Static Asset Store
    subgraph "Static Server"
        StaticModels["Static Models & Resources"]:::static
    end

    %% Core Engine
    subgraph "Core Engine"
        Loader["XML Loader"]:::core
        Interpreter["Interpreter & Search"]:::core
        MJNodes["MJ-Nodes Library"]:::core
        RuleEngine["Rule Engine & Symmetry"]:::core
        DataHelpers["Data & I/O Helpers"]:::core
    end

    %% WebAssembly Worker
    subgraph "WASM / Worker Process"
        WasmIndex["WASM Loader"]:::wasm
        WasmObserve["observe.ts"]:::wasm
        WasmOpt["optimization.ts"]:::wasm
        WasmSearch["search.ts"]:::wasm
        Worker["WASM Worker"]:::wasm
        NativeCore["Native C Core (.wasm)"]:::wasm
    end

    %% Browser Process
    subgraph "Browser Process"
        UI["React UI"]:::browser
        RenderEngine["Render Engine (WebGL)"]:::browser
    end

    %% Node Process
    subgraph "Node.js CLI"
        CLI["CLI Adapter"]:::cli
    end

    %% Data Flows
    StaticModels -->|XML models & rules| Loader
    UI -->|Load models| Loader
    CLI -->|Load models| Loader

    Loader -->|Rule graph| Interpreter
    Interpreter -->|Uses nodes| MJNodes
    Interpreter -->|Applies rules| RuleEngine
    Interpreter -->|Uses helpers| DataHelpers

    Interpreter -.->|Compute heavy tasks| WasmIndex
    WasmIndex -->|invoke observe/search/optimize| Worker
    Worker -->|Calls native core| NativeCore
    Worker -->|Returns results| Interpreter

    Interpreter -->|voxel grid| RenderEngine
    Interpreter -->|.vox binary| CLI

    %% Click Events
    click Loader "https://github.com/yuu6883/markovjuniorweb/blob/main/src/loader/index.ts"
    click Interpreter "https://github.com/yuu6883/markovjuniorweb/blob/main/src/interpreter.ts"
    click MJNodes "https://github.com/yuu6883/markovjuniorweb/tree/main/src/mj-nodes/"
    click RuleEngine "https://github.com/yuu6883/markovjuniorweb/blob/main/src/rule.ts"
    click DataHelpers "https://github.com/yuu6883/markovjuniorweb/blob/main/src/helpers/datastructures.ts"
    click DataHelpers "https://github.com/yuu6883/markovjuniorweb/blob/main/src/helpers/reader.ts"
    click DataHelpers "https://github.com/yuu6883/markovjuniorweb/blob/main/src/helpers/writer.ts"
    click DataHelpers "https://github.com/yuu6883/markovjuniorweb/blob/main/src/helpers/vox.ts"
    click WasmIndex "https://github.com/yuu6883/markovjuniorweb/blob/main/src/wasm/index.ts"
    click WasmObserve "https://github.com/yuu6883/markovjuniorweb/blob/main/src/wasm/observe.ts"
    click WasmOpt "https://github.com/yuu6883/markovjuniorweb/blob/main/src/wasm/optimization.ts"
    click WasmSearch "https://github.com/yuu6883/markovjuniorweb/blob/main/src/wasm/search.ts"
    click Worker "https://github.com/yuu6883/markovjuniorweb/blob/main/src/wasm/worker.ts"
    click NativeCore "https://github.com/yuu6883/markovjuniorweb/tree/main/src/native/"
    click UI "https://github.com/yuu6883/markovjuniorweb/blob/main/src/web/index.tsx"
    click RenderEngine "https://github.com/yuu6883/markovjuniorweb/blob/main/src/render/index.ts"
    click CLI "https://github.com/yuu6883/markovjuniorweb/blob/main/src/node/program.ts"
    click StaticModels "https://github.com/yuu6883/markovjuniorweb/blob/main/static/models.xml"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000;
    classDef wasm fill:#98FB98,stroke:#000;
    classDef browser fill:#FFA500,stroke:#000;
    classDef cli fill:#D3D3D3,stroke:#000;
    classDef static fill:#FFFF99,stroke:#000;
```
