# vtil-project/vtil-core architecture

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

- Interactive diagram: https://gitdiagram.com/vtil-project/vtil-core
- Repository: https://github.com/vtil-project/vtil-core

## Overview

VTIL is a core framework for binary de-obfuscation and de-virtualization: native instructions are lifted into a flexible virtual-machine intermediate language (VTIL), optimized, and can be emitted back into native formats. The graph preserves architecture support, PE handling, symbolic execution, and compiler optimization as distinct capabilities. Evidence is limited to the README and the supplied source index and excerpts; unsampled implementation links are omitted or marked unverified.

Main entry points: [`VTIL-Architecture/routine/basic_block.hpp`](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/basic_block.hpp) (Routines and Blocks), [`VTIL-Compiler/optimizer`](https://github.com/vtil-project/vtil-core/tree/master/VTIL-Compiler/optimizer) (Optimization Passes), [`VTIL-Architecture/routine/instruction.hpp`](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/instruction.hpp) (VTIL Instructions), [`VTIL-Common/arch`](https://github.com/vtil-project/vtil-core/tree/master/VTIL-Common/arch) (Native Disassembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_arch["Native Architecture"]
  node_disassembly["Native Disassembly"]
  node_registers["Register Descriptions<br/>[register_desc.hpp]"]
  node_native_emission["Native Code Emission"]
end

subgraph group_ir["VTIL Representation"]
  node_instruction_set["Instruction Set"]
  node_routine["Routines and Blocks<br/>[basic_block.hpp]"]
  node_instructions["VTIL Instructions<br/>[instruction.hpp]"]
  node_serialization["Routine Serialization<br/>[serialization.cpp]"]
end

subgraph group_analysis["Symbolic Analysis"]
  node_symbolic_variables["Symbolic Variables<br/>[variable.hpp]"]
  node_symbolic_context["Symbolic Context<br/>[context.cpp]"]
  node_symbolic_expressions["Expressions<br/>[expression.cpp]"]
  node_simplifier["Expression Simplifier<br/>[simplifier.cpp]"]
  node_directives["Rewrite Directives"]
  node_tracing["Execution Tracing<br/>[tracer.cpp]"]
  node_vm["Virtual Machine Interface<br/>[interface.cpp]"]
end

subgraph group_compiler["Optimization"]
  node_passes["Optimization Passes"]
  node_compiler_interface["Compiler Interface<br/>[interface.hpp]"]
end

subgraph group_common["Binary and Common"]
  node_pe["PE Image Support<br/>[winpe.cpp]"]
  node_common_utilities["Common Utilities<br/>[type_helpers.hpp]"]
end

node_analyst(("Binary Analyst"))

node_analyst -.->|"lifts binary"| node_disassembly
node_disassembly -.->|"produces VTIL"| node_routine
node_registers -->|"describes operands"| node_instructions
node_instruction_set -->|"defines operations"| node_instructions
node_routine -.->|"contains instructions"| node_instructions
node_routine -.->|"serializes"| node_serialization
node_symbolic_context -->|"reads and writes"| node_symbolic_variables
node_symbolic_variables -.->|"represents values"| node_symbolic_expressions
node_symbolic_expressions -->|"uses simplification"| node_simplifier
node_simplifier -->|"applies transforms"| node_directives
node_compiler_interface -.->|"runs passes"| node_passes
node_passes -.->|"optimizes VTIL"| node_routine
node_passes -->|"uses helpers"| node_common_utilities
node_tracing -->|"uses VM lambda"| node_vm
node_pe -.->|"supports image analysis"| node_analyst
node_routine -.->|"emits native code"| node_native_emission
node_routine -.->|"optimized by compiler"| node_passes

click node_disassembly "https://github.com/vtil-project/vtil-core/tree/master/VTIL-Common/arch"
click node_registers "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/arch/register_desc.hpp"
click node_instruction_set "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/arch/instruction_set.hpp"
click node_routine "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/basic_block.hpp"
click node_instructions "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/instruction.hpp"
click node_serialization "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/serialization.cpp"
click node_symbolic_variables "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/symex/variable.hpp"
click node_symbolic_context "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/symex/context.cpp"
click node_symbolic_expressions "https://github.com/vtil-project/vtil-core/blob/master/VTIL-SymEx/expressions/expression.cpp"
click node_simplifier "https://github.com/vtil-project/vtil-core/blob/master/VTIL-SymEx/simplifier/simplifier.cpp"
click node_directives "https://github.com/vtil-project/vtil-core/tree/master/VTIL-SymEx/directives"
click node_passes "https://github.com/vtil-project/vtil-core/tree/master/VTIL-Compiler/optimizer"
click node_compiler_interface "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Compiler/common/interface.hpp"
click node_tracing "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/trace/tracer.cpp"
click node_vm "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/vm/interface.cpp"
click node_pe "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Common/formats/winpe.cpp"
click node_native_emission "https://github.com/vtil-project/vtil-core/tree/master/VTIL-Common/arch"
click node_common_utilities "https://github.com/vtil-project/vtil-core/blob/master/VTIL-Common/util/type_helpers.hpp"

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_disassembly,node_registers,node_native_emission toneBlue
class node_instruction_set,node_routine,node_instructions,node_serialization toneAmber
class node_symbolic_variables,node_symbolic_context,node_symbolic_expressions,node_simplifier,node_directives,node_tracing,node_vm toneMint
class node_passes,node_compiler_interface toneRose
class node_pe,node_common_utilities,node_analyst toneIndigo
```

## Components

### Native Architecture

- [Native Disassembly](https://github.com/vtil-project/vtil-core/tree/master/VTIL-Common/arch): `VTIL-Common/arch`
- [Register Descriptions](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/arch/register_desc.hpp): `VTIL-Architecture/arch/register_desc.hpp`
- [Native Code Emission](https://github.com/vtil-project/vtil-core/tree/master/VTIL-Common/arch): `VTIL-Common/arch`

### VTIL Representation

- [Instruction Set](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/arch/instruction_set.hpp): `VTIL-Architecture/arch/instruction_set.hpp`
- [Routines and Blocks](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/basic_block.hpp): `VTIL-Architecture/routine/basic_block.hpp`
- [VTIL Instructions](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/instruction.hpp): `VTIL-Architecture/routine/instruction.hpp`
- [Routine Serialization](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/routine/serialization.cpp): `VTIL-Architecture/routine/serialization.cpp`

### Symbolic Analysis

- [Symbolic Variables](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/symex/variable.hpp): `VTIL-Architecture/symex/variable.hpp`
- [Symbolic Context](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/symex/context.cpp): `VTIL-Architecture/symex/context.cpp`
- [Expressions](https://github.com/vtil-project/vtil-core/blob/master/VTIL-SymEx/expressions/expression.cpp): `VTIL-SymEx/expressions/expression.cpp`
- [Expression Simplifier](https://github.com/vtil-project/vtil-core/blob/master/VTIL-SymEx/simplifier/simplifier.cpp): `VTIL-SymEx/simplifier/simplifier.cpp`
- [Rewrite Directives](https://github.com/vtil-project/vtil-core/tree/master/VTIL-SymEx/directives): `VTIL-SymEx/directives`
- [Execution Tracing](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/trace/tracer.cpp): `VTIL-Architecture/trace/tracer.cpp`
- [Virtual Machine Interface](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Architecture/vm/interface.cpp): `VTIL-Architecture/vm/interface.cpp`

### Optimization

- [Optimization Passes](https://github.com/vtil-project/vtil-core/tree/master/VTIL-Compiler/optimizer): `VTIL-Compiler/optimizer`
- [Compiler Interface](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Compiler/common/interface.hpp): `VTIL-Compiler/common/interface.hpp`

### Binary and Common

- [PE Image Support](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Common/formats/winpe.cpp): `VTIL-Common/formats/winpe.cpp`
- [Common Utilities](https://github.com/vtil-project/vtil-core/blob/master/VTIL-Common/util/type_helpers.hpp): `VTIL-Common/util/type_helpers.hpp`

### Other components

- **Binary Analyst**

## Connections

- Binary Analyst → Native Disassembly: lifts binary
- Native Disassembly → Routines and Blocks: produces VTIL
- Register Descriptions → VTIL Instructions: describes operands (evidence: `VTIL-Architecture/routine/instruction.hpp`)
- Instruction Set → VTIL Instructions: defines operations (evidence: `VTIL-Architecture/routine/instruction.hpp`)
- Routines and Blocks → VTIL Instructions: contains instructions (evidence: `VTIL-Architecture/routine/basic_block.hpp`)
- Routines and Blocks → Routine Serialization: serializes
- Symbolic Context → Symbolic Variables: reads and writes (evidence: `VTIL-Architecture/symex/context.cpp`)
- Symbolic Variables → Expressions: represents values
- Expressions → Expression Simplifier: uses simplification (evidence: `VTIL-SymEx/expressions/expression.cpp`)
- Expression Simplifier → Rewrite Directives: applies transforms (evidence: `VTIL-SymEx/simplifier/simplifier.cpp`)
- Compiler Interface → Optimization Passes: runs passes
- Optimization Passes → Routines and Blocks: optimizes VTIL
- Optimization Passes → Common Utilities: uses helpers (evidence: `VTIL-Compiler/optimizer/fast_propagation_pass.cpp`)
- Execution Tracing → Virtual Machine Interface: uses VM lambda (evidence: `VTIL-Architecture/trace/tracer.cpp`)
- PE Image Support → Binary Analyst: supports image analysis
- Routines and Blocks → Native Code Emission: emits native code
- Routines and Blocks → Optimization Passes: optimized by compiler