# xeonise/medal2 architecture

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

- Interactive diagram: https://gitdiagram.com/xeonise/medal2
- Repository: https://github.com/xeonise/medal2

## Overview

##### Project Type and Purpose
- This repository is a language-tooling project: a decompiler for Lua bytecode (both Lua 5.1 and Roblox’s Luau dialect). It is organized as a workspace of Cargo crates that implement:
- Bytecode deserialization (lua51-deserializer, luau-lifter/deserializer)
- Bytecode-to-AST lifting (lua51-lifter, luau-lifter)
- AST representation and transformations (ast)
- Control-flow analysis and SSA transformations (cfg)
- Control-flow restructuring back into structured AST (restructure)
- A decompilation server or worker interface (decomp-server, luau-worker)

##### Top-Level Components
- Crates:
- lua51-deserializer: parse .luac chunk to instruction structures
- lua51-lifter: lift 5.1 instructions into an initial AST
- luau-lifter: parse and lift Luau bytecode into AST
- ast: unified AST node definitions, name resolution, formatting to source code
- cfg: build and analyze control-flow graphs and SSA form
- restructure: restructure SSA/CFG back into structured constructs (if, loops)
- decomp-server: HTTP/CLI server exposing decompilation as a service
- luau-worker: a WASM or edge-worker wrapper around the decompilation pipeline
- Supporting files:
- playermodule.bin, script.lua – sample inputs
- wrangler.toml – Cloudflare Workers config (for luau-worker)

##### Component Interactions
- Data Flow:
[Bytecode File]
→ (1) Deserializer → Instr. Stream
→ (2) Lifter       → Raw AST
→ (3) CFG Builder  → SSA/CFG
→ (4) Restructurer → Structured AST
→ (5) Formatter    → Decompiled Source
→ (6) Output to Console / HTTP Response / Worker Response
- Server/Worker:
- Accepts bytecode via HTTP or CLI
- Invokes the pipeline above
- Returns decompiled Lua source

##### Architectural Patterns and Principles
- Modular, single-responsibility crates (each crate focuses on one stage of decompilation)
- Pipeline pattern: chain of transformations from raw bytes to final text
- Clear separation of concerns: parsing, lifter, analysis, restructuring, formatting
- Reusability: ast and cfg crates are shared by both lua51-lifter and luau-lifter

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef parsing fill:#ADD8E6,stroke:#000;
    classDef analysis fill:#90EE90,stroke:#000;
    classDef restructure fill:#FFA500,stroke:#000;
    classDef interface fill:#DDA0DD,stroke:#000;
    classDef io fill:#D3D3D3,stroke:#000;

    Client["Client\n(HTTP/CLI)"]:::interface
    DecompServer["Decomp-Server\n(decomp-server)"]:::interface
    LuauWorker["Luau Worker\n(luau-worker)"]:::interface

    Client --> DecompServer
    Client --> LuauWorker
    DecompServer --> L0
    LuauWorker --> L0

    L0["Bytecode File\n(playermodule.bin, script.lua)"]:::io

    L0 -->|""Lua51""| Lua51Deserializer
    L0 -->|""Luau""| LuauDeserializer

    Lua51Deserializer["Lua51 Deserializer\n(lua51-deserializer)"]:::parsing
    LuauDeserializer["Luau Deserializer\n(luau-lifter/deserializer)"]:::parsing

    Lua51Deserializer --> Lua51Lifter
    LuauDeserializer --> LuauLifter

    Lua51Lifter["Lua51 Lifter\n(lua51-lifter)"]:::parsing
    LuauLifter["Luau Lifter\n(luau-lifter)"]:::parsing

    Lua51Lifter --> AST
    LuauLifter --> AST

    AST["AST Module\n(ast)"]:::analysis
    AST --> CFG

    CFG["CFG & SSA Module\n(cfg)"]:::analysis
    CFG --> Restructure

    Restructure["Restructurer\n(restructure)"]:::restructure
    Restructure --> Formatter

    Formatter["Formatter\n(ast/src/formatter.rs)"]:::restructure
    Formatter --> Output

    Output["Decompiled Source\n(.lua)"]:::io
    Formatter --> DecompServer
    Formatter --> LuauWorker

    click Lua51Deserializer "https://github.com/xeonise/medal2/tree/main/lua51-deserializer/src"
    click Lua51Lifter "https://github.com/xeonise/medal2/tree/main/lua51-lifter/src"
    click LuauDeserializer "https://github.com/xeonise/medal2/tree/main/luau-lifter/src/deserializer"
    click LuauLifter "https://github.com/xeonise/medal2/tree/main/luau-lifter/src"
    click AST "https://github.com/xeonise/medal2/tree/main/ast/src"
    click CFG "https://github.com/xeonise/medal2/tree/main/cfg/src"
    click Restructure "https://github.com/xeonise/medal2/tree/main/restructure/src"
    click DecompServer "https://github.com/xeonise/medal2/tree/main/decomp-server/src"
    click LuauWorker "https://github.com/xeonise/medal2/blob/main/luau-worker/src/lib.rs"
```
