# caomod2077/deobfuscator-luraph-v15 architecture

> Architecture diagram of the GitHub repository caomod2077/deobfuscator-luraph-v15, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/caomod2077/deobfuscator-luraph-v15
- Repository: https://github.com/caomod2077/deobfuscator-luraph-v15

## Overview

This is a command-line deobfuscator for Roblox Luau protected by Luraph v15. Its principal workflow detects the obfuscator, instruments and runs the script in an offline Luau sandbox to capture execution data, then lifts captured VM protos into structured Luau and polishes the output. It also supports detection-only and trace-only modes. The README documents the broad stages; sampled excerpts are partial, so some orchestration links follow that documentation rather than inspected call sites.

Main entry points: [`src/driver.js`](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/driver.js) (Pipeline driver), [`core/obfuscators/luraph_v15/devirt.py`](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/obfuscators/luraph_v15/devirt.py) (Proto devirtualizer), [`core/backend.py`](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/backend.py) (Backend analysis), [`src/harness.js`](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/harness.js) (Offline sandbox)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and routing"]
  node_cli["CLI and jobs<br/>[deob.js]"]
  node_detection["Luraph detection<br/>[detect.js]"]
  node_driver["Pipeline driver<br/>[driver.js]"]
end

subgraph group_capture["Analysis and capture"]
  node_astmap["VM mapping<br/>[vmmap.js]"]
  node_sandbox["Offline sandbox<br/>[harness.js]"]
  node_trace["Trace rendering<br/>[traceout.js]"]
end

subgraph group_lifting["VM reconstruction"]
  node_bridge["Python bridge<br/>[devirt_bridge.py]"]
  node_devirt["Proto devirtualizer<br/>[devirt.py]"]
  node_ir["Lifted IR<br/>[ir.py]"]
  node_cfg["CFG structuring<br/>[structure.py]"]
  node_loops["Loop recovery<br/>[loops.py]"]
end

subgraph group_polish["Output recovery"]
  node_backend["Backend analysis<br/>[backend.py]"]
  node_variables["Variable recovery<br/>[variables.py]"]
  node_names["Contextual naming<br/>[names.py]"]
  node_codegen["Luau rendering<br/>[codegen.py]"]
  node_tidy["Source cleanup<br/>[tidy.js]"]
end

node_user(("Script user"))
node_luau["Luau runtime"]
node_result["Recovered Luau"]

node_user -->|"provides script"| node_cli
node_cli -->|"detects type"| node_detection
node_cli -->|"starts job"| node_driver
node_driver -->|"maps VM"| node_astmap
node_driver -->|"runs instrumented script"| node_sandbox
node_astmap -->|"informs hooks"| node_sandbox
node_sandbox -->|"executes in"| node_luau
node_sandbox -->|"emits execution data"| node_trace
node_driver -->|"requests lifting"| node_bridge
node_bridge -->|"invokes devirtualizer"| node_devirt
node_devirt -->|"builds"| node_ir
node_devirt -->|"structures instructions"| node_cfg
node_cfg -->|"recovers loops"| node_loops
node_devirt -->|"analyzes lifted code"| node_backend
node_backend -->|"recovers variables"| node_variables
node_backend -->|"infers names"| node_names
node_backend -->|"renders source"| node_codegen
node_driver -.->|"selects trace mode"| node_trace
node_driver -->|"cleans output"| node_tidy
node_tidy -->|"writes source"| node_result
node_codegen -->|"produces source"| node_result

click node_cli "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/deob.js"
click node_detection "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/detect.js"
click node_driver "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/driver.js"
click node_astmap "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/vmmap.js"
click node_sandbox "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/harness.js"
click node_trace "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/traceout.js"
click node_bridge "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/devirt_bridge.py"
click node_devirt "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/obfuscators/luraph_v15/devirt.py"
click node_ir "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/ir.py"
click node_cfg "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/structure.py"
click node_loops "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/loops.py"
click node_backend "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/backend.py"
click node_variables "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/variables.py"
click node_names "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/names.py"
click node_codegen "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/codegen.py"
click node_tidy "https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/tidy.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_detection,node_driver,node_user toneBlue
class node_astmap,node_sandbox,node_trace toneAmber
class node_bridge,node_devirt,node_ir,node_cfg,node_loops toneMint
class node_backend,node_variables,node_names,node_codegen,node_tidy toneRose
class node_luau,node_result toneIndigo
```

## Components

### CLI and routing

- [CLI and jobs](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/deob.js): `deob.js`
- [Luraph detection](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/detect.js): `src/detect.js`
- [Pipeline driver](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/driver.js): `src/driver.js`

### Analysis and capture

- [VM mapping](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/vmmap.js): `src/vmmap.js`
- [Offline sandbox](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/harness.js): `src/harness.js`
- [Trace rendering](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/traceout.js): `src/traceout.js`

### VM reconstruction

- [Python bridge](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/devirt_bridge.py): `src/devirt_bridge.py`
- [Proto devirtualizer](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/obfuscators/luraph_v15/devirt.py): `core/obfuscators/luraph_v15/devirt.py`
- [Lifted IR](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/ir.py): `core/ir.py`
- [CFG structuring](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/structure.py): `core/structure.py`
- [Loop recovery](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/loops.py): `core/loops.py`

### Output recovery

- [Backend analysis](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/backend.py): `core/backend.py`
- [Variable recovery](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/variables.py): `core/variables.py`
- [Contextual naming](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/names.py): `core/names.py`
- [Luau rendering](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/core/codegen.py): `core/codegen.py`
- [Source cleanup](https://github.com/caomod2077/deobfuscator-luraph-v15/blob/master/src/tidy.js): `src/tidy.js`

### Other components

- **Script user**
- **Luau runtime**
- **Recovered Luau**

## Connections

- Script user → CLI and jobs: provides script
- CLI and jobs → Luraph detection: detects type
- CLI and jobs → Pipeline driver: starts job
- Pipeline driver → VM mapping: maps VM
- Pipeline driver → Offline sandbox: runs instrumented script
- VM mapping → Offline sandbox: informs hooks
- Offline sandbox → Luau runtime: executes in
- Offline sandbox → Trace rendering: emits execution data
- Pipeline driver → Python bridge: requests lifting
- Python bridge → Proto devirtualizer: invokes devirtualizer
- Proto devirtualizer → Lifted IR: builds
- Proto devirtualizer → CFG structuring: structures instructions
- CFG structuring → Loop recovery: recovers loops
- Proto devirtualizer → Backend analysis: analyzes lifted code
- Backend analysis → Variable recovery: recovers variables
- Backend analysis → Contextual naming: infers names
- Backend analysis → Luau rendering: renders source
- Pipeline driver → Trace rendering: selects trace mode
- Pipeline driver → Source cleanup: cleans output
- Source cleanup → Recovered Luau: writes source
- Luau rendering → Recovered Luau: produces source