# n3rdl0rd/crashlink architecture

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

- Interactive diagram: https://gitdiagram.com/n3rdl0rd/crashlink
- Repository: https://github.com/n3rdl0rd/crashlink

## Overview

##### Project type and purpose
- This is an open‑source, pure‑Python library and CLI tool (“Swiss Army knife”) for working with HashLink bytecode: parsing, serializing, disassembling, (limited) decompiling, assembling, patching, interpreting, and testing. It also provides a built‑in testing harness (crashtest), auto‑generated documentation, and a small CLI.

##### File structure
- Top‑level components:
- crashlink/ – the core library (modules: core, asm, disasm, decomp, pseudo, opcodes, interp, errors, globals; __main__.py entry point)
- crashtest/ – the test‑harness CLI (build.py, run.py, models.py, JSON “runs” outputs, Jinja templates for HTML)
- docs/ – generated API docs and static assets (flow.svg, templates, out‑dirs)
- tests/ – unit tests (pytest-based) and Haxe sample files under tests/haxe/ for decompiler validation
- justfile, pyproject.toml, GitHub Actions workflow – build, test, doc generation, CI/CD

- Architectural clues:
- Clear separation between core library, CLI wrappers, test harness, and documentation
- Modular decomposition by functionality (parsing, disassembly, decompilation, pseudo‑code generation, VM interpretation)
- Use of an external command runner (just/uv) and CI (GitHub Actions)

##### Pull additional insights from the README
- Describes a pipeline: Deserialisation → Disassembly → (future) IR lifting & optimization → Pseudocode targets → (optional) recompilation/patching
- Mentions dependencies: zero pure‑Python core, optional extras (tqdm, graphviz) for progress bars & CFG generation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Frontends
    subgraph "CLI Frontends"
        cr1["crashlink CLI"]:::cli
        cr2["crashtest CLI"]:::cli
    end

    %% Core Library Modules
    subgraph "Core Library Modules"
        parser["Parser/Deserializer\ncore.py"]:::core
        globals["Global Bytecode Definitions\ngobals.py"]:::core
        opcodes["Opcode Definitions\nopcodes.py"]:::core
        asm["Assembler\nasm.py"]:::core
        disasm["Disassembler\ndisasm.py"]:::core
        decomp["Decompiler\ndecomp.py"]:::core
        pseudo["Pseudocode Back-ends\npseudo.py"]:::core
        interp_std["Interpreter Std\ninterp/std.py"]:::core
        interp_vm["Interpreter VM\ninterp/vm.py"]:::core
        errors["Error Handling\nerrors.py"]:::core
        IR(("Bytecode IR")):::core
    end

    %% Test Harness
    subgraph "Test Harness"
        build["Build Logic\nbuild.py"]:::cli
        run["Run Logic\nrun.py"]:::cli
        models["Data Models\nmodels.py"]:::cli
    end

    %% Data Stores
    subgraph "Data Stores"
        hl["Input .hl files"]:::data
        haxe["Haxe Test Sources"]:::data
        textOut["Text Output (stdout)"]:::data
        pseudOut["Pseudocode Output"]:::data
        serialized["Serialized .hl"]:::data
        patched["Patched Bytecode"]:::data
        jsonruns["JSON Runs"]:::data
        htmltemplates["HTML Templates"]:::data
        docs_out["Generated Documentation"]:::data
    end

    %% Documentation Generator
    subgraph "Documentation Generator"
        docgen["Doc Generator\ntemplates/config.mako"]:::cli
    end

    %% External Dependencies
    subgraph "External Dependencies"
        graphviz["Graphviz"]:::ext
        tqdm["tqdm"]:::ext
        just["Task Automation\njustfile"]:::ext
        workflow["CI Workflow\n.github/workflows/python-package.yml"]:::ext
    end

    %% Data Flow Pipeline
    hl --> parser --> IR
    IR --> disasm --> textOut
    IR --> decomp --> pseudOut
    IR --> asm --> serialized
    pseudOut --> asm --> patched

    %% CLI Invocations
    cr1 --> parser
    cr1 --> disasm
    cr1 --> decomp
    cr1 --> asm
    cr1 --> interp_std
    cr1 --> interp_vm

    %% Test Harness Flow
    cr2 --> haxe
    cr2 --> pseudOut
    cr2 --> run
    run --> models
    models --> jsonruns
    models --> htmltemplates

    %% Documentation Flow
    docgen --> parser
    docgen --> asm
    docgen --> disasm
    docgen --> decomp
    docgen --> pseudo
    docgen --> interp_std
    docgen --> interp_vm
    docgen --> docs_out

    %% External Tools Usage
    disasm --> graphviz
    pseudo --> graphviz
    cr1 --> tqdm
    just --> cr1
    just --> cr2
    workflow --> just

    %% Click Events
    click cr1 "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/__main__.py"
    click cr2 "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/__main__.py"
    click parser "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/core.py"
    click globals "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/globals.py"
    click opcodes "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/opcodes.py"
    click asm "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/asm.py"
    click disasm "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/disasm.py"
    click decomp "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/decomp.py"
    click pseudo "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/pseudo.py"
    click interp_std "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/interp/std.py"
    click interp_vm "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/interp/vm.py"
    click errors "https://github.com/n3rdl0rd/crashlink/blob/main/crashlink/errors.py"
    click build "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/build.py"
    click run "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/run.py"
    click models "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/models.py"
    click jsonruns "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/runs/*.json"
    click htmltemplates "https://github.com/n3rdl0rd/crashlink/blob/main/crashtest/templates/index.html"
    click docgen "https://github.com/n3rdl0rd/crashlink/blob/main/docs/templates/config.mako"
    click docs_out "https://github.com/n3rdl0rd/crashlink/blob/main/docs/crashlink/*.html"
    click just "https://github.com/n3rdl0rd/crashlink/tree/main/justfile"
    click workflow "https://github.com/n3rdl0rd/crashlink/blob/main/.github/workflows/python-package.yml"

    %% Styles
    classDef core fill:#E3F2FD,stroke:#1E88E5,stroke-width:1px
    classDef cli fill:#E8F5E9,stroke:#43A047,stroke-width:1px
    classDef data fill:#FFF3E0,stroke:#FB8C00,stroke-width:1px
    classDef ext fill:#ECEFF1,stroke:#546E7A,stroke-width:1px
```
