# donzgold/justmc_compilator architecture

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

- Interactive diagram: https://gitdiagram.com/donzgold/justmc_compilator
- Repository: https://github.com/donzgold/justmc_compilator

## Overview

##### Project Type & Purpose
- JMCC is a command‐line compiler/transpiler written in Python.
- It takes `.jc` source files (JustMC script language) and produces JSON snippets for the JustMC server, optionally uploading them to a cloud service.
- It also provides decompilation (JSON → `.jc`), documentation generation, code‐completion assets, and NBT manipulations.

##### File‐Structure Analysis
Top‐level components:
- `jmcc.py` – CLI entry point & argument parser
- `compilator.py` – main compile engine (lexing, parsing, AST, semantic checks, codegen)
- `decompilator.py` – reverse engine (JSON → `.jc`)
- `nbtworker.py` – handles NBT (Minecraft data tags) transformations
- `md_generator.py` – renders documentation/Markdown from templates & data
- `data/` & `new_data/` – JSON + `.properties` files defining actions, blocks, events, languages, values
- `assets/completions.json` – code‐completion metadata for editors
- `documentation/` – handwritten docs in English & Russian (for users)
- `jmcc.properties` – configuration for the compiler

##### Architectural Insights from README
- Single‐process, plug‐in style modules
- Pipeline pattern in `compilator.py`: parse → semantic analysis → generate JSON → write or upload
- Optional sub‐commands: `compile`, `decompile`, `docs`, etc.
- Uses standard Python + `requests` for HTTP uploads

##### Main Components & Interactions
a. Components
1. CLI Layer (jmcc.py)
2. Parser & AST Builder (inside compilator.py)
3. Semantic Analyzer (type checking, symbol tables)
4. Code Generator (JSON emitter)
5. Data Repository (data/, new_data/)
6. NBT Worker (nbtworker.py)
7. Output Module
– File Writer (writes `.json`)
– Uploader (HTTP client via `requests`)
8. Decompiler (decompilator.py)
9. Documentation Generator (md_generator.py)
10. Code‐Completion Asset Builder (assets/completions.json)

b. Relationships & Data Flow
- User invokes `jmcc.py → compile`
- CLI loads configuration, command‐dispatches to the Compiler Engine
- Compiler Engine pulls definitions from Data Repository → feeds into Parser & Semantic phases
- NBT Worker is called by Code Generator to produce correct NBT JSON segments
- Generated JSON goes to Output Module → either disk (`.json`) or Uploader → Cloud API
- Decompiler is a separate command path in CLI, reading JSON + Data Repository → reconstructing `.jc`
- Documentation Generator reads Data Repository & `documentation/` templates → builds updated MD docs

c. Architectural Patterns & Principles
- Pipeline / Chain of Responsibility for compile phases
- Single‐responsibility modules (parsing vs. codegen vs. NBT vs. docs)
- Data‐driven design: all commands, events, blocks, etc. defined in JSON under `data/`
- Plugin‐like subcommands within a single‐process CLI

d. Key Technologies
- Python3 modules & packages
- JSON & Java‐style `.properties` for data/config
- `requests` for HTTP uploads
- Markdown for documentation

## Diagram (Mermaid)

```mermaid
graph TB
    %% External User
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI (jmcc.py)"]:::cli
    end

    %% Compiler Engine
    subgraph "Compiler Engine"
        Parser["Parser & AST Builder\n(compilator.py)"]:::engine
        Semantic["Semantic Analyzer\n(compilator.py)"]:::engine
        CodeGen["Code Generator\n(compilator.py)"]:::engine
        subgraph "Output Module"
            FileWrite["File Writer\n(compilator.py)"]:::engine
            Uploader["Uploader\n(compilator.py)"]:::engine
        end
    end

    %% Data Repositories & Config
    Data["Data Repository\ndata/"]:::data
    NewData["Data Repository\nnew_data/"]:::data
    Config["Config\n(jmcc.properties)"]:::data

    %% Utilities
    NBT["NBT Worker\n(nbtworker.py)"]:::util
    Decomp["Decompiler\n(decompilator.py)"]:::util
    DocGen["Documentation Generator\n(md_generator.py)"]:::util
    Assets["Code-Completion Asset Builder\n(assets/completions.json)"]:::util
    DocsSrc["Templates\n(documentation/)"]:::util
    DocumentationOut["Generated Docs\n(.md)"]:::util
    CompletionOut["Generated Completions\n(.json)"]:::util

    %% External Services
    Cloud["Cloud Upload Service"]:::external

    %% Main Compile Flow
    User -->|"invokes 'compile'"| CLI
    CLI --> Parser
    Parser --> Semantic
    Semantic --> CodeGen
    CodeGen --> FileWrite
    CodeGen --> Uploader
    Uploader -->|"HTTP POST"| Cloud
    CodeGen -->|"calls"| NBT

    %% Data Flows into Compiler
    Data --> Parser
    NewData --> Parser

    %% Config
    Config --> CLI

    %% Decompile Flow
    User -->|"invokes 'decompile'"| CLI
    CLI --> Decomp
    Decomp --> Data
    Decomp --> NewData
    Decomp -->|"outputs .jc"| User

    %% Documentation Flow
    User -->|"invokes 'docs'"| CLI
    CLI --> DocGen
    DocGen --> Data
    DocGen --> NewData
    DocGen --> DocsSrc
    DocGen -->|"outputs MD"| DocumentationOut

    %% Code-Completion Flow
    User -->|"invokes 'completions'"| CLI
    CLI --> Assets
    Assets --> Data
    Assets --> NewData
    Assets -->|"outputs JSON"| CompletionOut

    %% Click Events
    click CLI "https://github.com/donzgold/justmc_compilator/blob/master/jmcc.py"
    click Parser "https://github.com/donzgold/justmc_compilator/blob/master/compilator.py"
    click Semantic "https://github.com/donzgold/justmc_compilator/blob/master/compilator.py"
    click CodeGen "https://github.com/donzgold/justmc_compilator/blob/master/compilator.py"
    click FileWrite "https://github.com/donzgold/justmc_compilator/blob/master/compilator.py"
    click Uploader "https://github.com/donzgold/justmc_compilator/blob/master/compilator.py"
    click Data "https://github.com/donzgold/justmc_compilator/tree/master/data/"
    click NewData "https://github.com/donzgold/justmc_compilator/tree/master/new_data/"
    click Config "https://github.com/donzgold/justmc_compilator/blob/master/jmcc.properties"
    click NBT "https://github.com/donzgold/justmc_compilator/blob/master/nbtworker.py"
    click Decomp "https://github.com/donzgold/justmc_compilator/blob/master/decompilator.py"
    click DocGen "https://github.com/donzgold/justmc_compilator/blob/master/md_generator.py"
    click Assets "https://github.com/donzgold/justmc_compilator/blob/master/assets/completions.json"
    click DocsSrc "https://github.com/donzgold/justmc_compilator/tree/master/documentation/"

    %% Styles
    classDef cli fill:#9f6,stroke:#080;
    classDef engine fill:#6cf,stroke:#039;
    classDef data fill:#fa6,stroke:#c50;
    classDef util fill:#c6f,stroke:#60c;
    classDef external fill:#ddd,stroke:#999;
```
