# rizinorg/rizin architecture

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

- Interactive diagram: https://gitdiagram.com/rizinorg/rizin
- Repository: https://github.com/rizinorg/rizin

## Overview

1. Rizin is a C-based reverse-engineering platform built as a layered library plus thin CLI tools. The main reusable surface lives under `librz/include`, while the implementation is split into focused modules under `librz/*`. The user-facing executables are wrappers around that library, not separate apps with their own logic.

2. The architectural center is `librz/core`. It orchestrates the rest of the system: opening files, seeking, disassembly, analysis, debugging, search, flags, types, projects, and command execution. If you want one “hub” box in a diagram, it is `core`, because almost every interactive workflow passes through it.

3. Binary ingestion starts in the I/O and binary-format layers. `librz/io` abstracts file descriptors, memory, caches, maps, remote sources, and special transports. `librz/bin` then identifies and parses executable/container formats such as ELF, PE, Mach-O, DWARF/PDB-rich binaries, Java class files, WASM, firmware images, and many console-specific formats. This boundary is important: IO gets bytes; bin interprets structure.

4. Analysis is architecture-driven and heavily plugin-oriented. `librz/arch` contains the generic analysis framework plus per-ISA implementations for disassembly, instruction semantics, control-flow, calling conventions, RTTI, and platform profiles. The `librz/arch/isa`, `isa_gnu`, `p`, `p_gnu`, and `opcodes` trees show that much of the CPU-specific behavior is code-generated or table-driven rather than hardcoded in a single engine.

5. Rizin models instruction behavior in two complementary ways: ESIL and IL. ESIL lives under `librz/arch/esil` and is used for emulation-like semantic evaluation, tracing, and analysis support. The newer IL layer is under `librz/il` and provides a more structured intermediate representation with validation, export, graphing, and VM evaluation. In a diagram, both sit beneath higher analysis features and above raw disassembly.

6. Debugging is a separate subsystem, not a special mode inside analysis. `librz/debug` provides breakpoints, register access, traces, signals, process/session management, and platform-specific backends for Linux, Windows, macOS/XNU, BSDs, and remote protocols. IO also participates here through debug-oriented transports under `librz/io/p` and related wrappers, so “debugged process” is effectively another IO source.

7. The command-line and visual UI layer is handled by `librz/cons` and `librz/core/cmd` plus the TUI code under `librz/core/tui`. Command parsing is data-driven via `librz/core/cmd_descs`, and the repo also includes a dedicated shell parser subproject for the interactive command language. The result is an interactive console where commands are translated into core operations, with output formatting handled separately by the console layer.

8. Several cross-cutting services provide specialized capabilities to the core workflows: `librz/search` for byte/string/regexp/entropy/hash/magic searches, `librz/hash` for hashing and similarity functions, `librz/crypto` for encoding/crypto primitives, `librz/type` and `librz/reg` for type systems and register profiles, and `librz/flag`/`librz/mark`/`librz/project` for user state. These are not isolated utilities; they feed analysis, printing, and serialization throughout the product.

9. A major design boundary is the use of declarative data files. Large parts of architecture metadata live in `.sdb.txt` tables under `librz/arch`, `librz/syscall`, `librz/type`, `librz/reg`, and `librz/bin`. These tables define opcodes, syscalls, calling conventions, platform profiles, and format details, making many subsystems data-driven and easier to extend without changing the engine.

10. The repo exposes multiple frontends, all thin relative to the library. The top-level tools include `rizin`, `rz-bin`, `rz-asm`, `rz-ar`, `rz-diff`, `rz-find`, `rz-hash`, `rz-gg`, `rz-run`, `rz-sign`, `rz-ax`, and `rz-test`. Each tool focuses on a narrow slice of the core capabilities, but they share the same underlying library and plugin ecosystem.

11. Remote and automation paths are first-class. `librz/socket` and `librz/core/rtr*` support pipe, TCP/HTTP, process, and shell-style connectivity, while the `examples/api` tree shows embeddable APIs for hashes, signatures, and syscalls. The README’s `rzpipe` mention reflects the intended external scripting boundary: other languages call into Rizin rather than reimplementing the analysis pipeline.

12. Build and portability are architectural concerns, not afterthoughts. The project is built with Meson and relies on bundled subprojects/wraps for optional dependencies like capstone, zydis, tree-sitter, zlib/zstd/lzma/libzip, crypto libraries, and platform shims. The extensive CI, cross-compilation, and OS-specific directories show that the codebase is designed to produce the same layered product across many operating systems and architectures.

13. Testing mirrors the architecture. `test/unit` checks the foundational utilities and subsystems, `test/integration` exercises cross-module flows like binary loading, analysis, DWARF/PDB, projects, and remote/debug interactions, and `test/db` contains golden inputs/outputs for formats, commands, analysis, and disassembly. This structure reflects the real dependency chain: utilities → format/arch/debug/search → core command flows → tool behavior.

Main entry points: [`librz/core`](https://github.com/rizinorg/rizin/tree/dev/librz/core) (Core Hub), [`librz/arch`](https://github.com/rizinorg/rizin/tree/dev/librz/arch) (Arch Engine), [`librz/include`](https://github.com/rizinorg/rizin/tree/dev/librz/include) (Public API), [`test`](https://github.com/rizinorg/rizin/tree/dev/test) (Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_lib["Library"]
  node_n_include["Public API<br/>headers"]
  node_n_core["Core Hub<br/>orchestrator"]
  node_n_io["IO Layer<br/>byte access"]
  node_n_bin["Binary Loader<br/>format parser"]
  node_n_arch["Arch Engine<br/>analysis framework"]
  node_n_esil["ESIL<br/>semantic eval"]
  node_n_il["RZIL<br/>intermediate IR"]
  node_n_debug["Debug Core<br/>debug subsystem"]
  node_n_cons["Console<br/>output/input"]
  node_n_search["Search<br/>match engine"]
  node_n_type["Types<br/>type system"]
  node_n_reg["Registers<br/>profiles"]
  node_n_state["State DB<br/>flags/projects"]
  node_n_cmd["Cmd Router<br/>interactive commands"]
  node_n_tui["TUI<br/>visual interface"]
end

subgraph group_grp_front["Frontends"]
  node_n_tools["CLI Tools<br/>frontends"]
  node_n_shell["Shell Parser<br/>command grammar"]
end

subgraph group_grp_ext["Plugins & Data"]
  node_n_plugins["Plugins<br/>backend modules"]
  node_n_tables["Data Tables<br/>sdb metadata"]
  node_n_socket["Remote IO<br/>network transport"]
  node_n_crypto["Crypto<br/>encoding primitives"]
end

subgraph group_grp_support["Support"]
  node_n_build["Build System<br/>meson build<br/>[meson.build]"]
  node_n_tests["Tests<br/>verification"]
end

node_n_tools -->|"dispatches"| node_n_cmd
node_n_tools -->|"drives"| node_n_core
node_n_cmd -->|"invokes"| node_n_core
node_n_tui -->|"issues"| node_n_cmd
node_n_core -->|"reads"| node_n_io
node_n_core -->|"loads"| node_n_bin
node_n_core -->|"analyzes"| node_n_arch
node_n_core -->|"debugs"| node_n_debug
node_n_core -->|"searches"| node_n_search
node_n_core -->|"types"| node_n_type
node_n_core -->|"profiles"| node_n_reg
node_n_core -->|"persists"| node_n_state
node_n_core -->|"uses"| node_n_crypto
node_n_arch -->|"semantics"| node_n_esil
node_n_arch -->|"lowers"| node_n_il
node_n_bin -->|"consults"| node_n_tables
node_n_arch -->|"consults"| node_n_tables
node_n_debug -->|"transports"| node_n_socket
node_n_io -->|"wraps"| node_n_socket
node_n_shell -->|"parses"| node_n_cmd
node_n_include -->|"exports"| node_n_core
node_n_include -->|"exports"| node_n_io
node_n_include -->|"exports"| node_n_arch
node_n_include -->|"exports"| node_n_debug
node_n_include -->|"exports"| node_n_il
node_n_plugins -->|"extends"| node_n_arch
node_n_plugins -->|"extends"| node_n_bin
node_n_plugins -->|"extends"| node_n_debug
node_n_plugins -->|"extends"| node_n_io
node_n_build -->|"assembles"| node_n_plugins
node_n_build -->|"produces"| node_n_tools
node_n_tests -->|"verifies"| node_n_core
node_n_tests -->|"verifies"| node_n_bin
node_n_tests -->|"verifies"| node_n_arch
node_n_tests -->|"verifies"| node_n_debug
node_n_tests -->|"verifies"| node_n_cmd

click node_n_include "https://github.com/rizinorg/rizin/tree/dev/librz/include"
click node_n_core "https://github.com/rizinorg/rizin/tree/dev/librz/core"
click node_n_io "https://github.com/rizinorg/rizin/tree/dev/librz/io"
click node_n_bin "https://github.com/rizinorg/rizin/tree/dev/librz/bin"
click node_n_arch "https://github.com/rizinorg/rizin/tree/dev/librz/arch"
click node_n_esil "https://github.com/rizinorg/rizin/tree/dev/librz/arch/esil"
click node_n_il "https://github.com/rizinorg/rizin/tree/dev/librz/il"
click node_n_debug "https://github.com/rizinorg/rizin/tree/dev/librz/debug"
click node_n_cons "https://github.com/rizinorg/rizin/tree/dev/librz/cons"
click node_n_search "https://github.com/rizinorg/rizin/tree/dev/librz/search"
click node_n_type "https://github.com/rizinorg/rizin/tree/dev/librz/type"
click node_n_reg "https://github.com/rizinorg/rizin/tree/dev/librz/reg"
click node_n_cmd "https://github.com/rizinorg/rizin/tree/dev/librz/core/cmd"
click node_n_tui "https://github.com/rizinorg/rizin/tree/dev/librz/core/tui"
click node_n_tools "https://github.com/rizinorg/rizin/tree/dev/librz/main"
click node_n_shell "https://github.com/rizinorg/rizin/tree/dev/subprojects/rizin-shell-parser"
click node_n_socket "https://github.com/rizinorg/rizin/tree/dev/librz/socket"
click node_n_crypto "https://github.com/rizinorg/rizin/tree/dev/librz/crypto"
click node_n_build "https://github.com/rizinorg/rizin/blob/dev/meson.build"
click node_n_tests "https://github.com/rizinorg/rizin/tree/dev/test"

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_n_include,node_n_core,node_n_io,node_n_bin,node_n_arch,node_n_esil,node_n_il,node_n_debug,node_n_cons,node_n_search,node_n_type,node_n_reg,node_n_state,node_n_cmd,node_n_tui toneBlue
class node_n_tools,node_n_shell toneAmber
class node_n_plugins,node_n_tables,node_n_socket,node_n_crypto toneMint
class node_n_build,node_n_tests toneRose
```

## Components

### Library

Reusable C library surface and core subsystems.

- [Public API](https://github.com/rizinorg/rizin/tree/dev/librz/include): headers · Primary reusable headers and exported interfaces under librz/include. · `librz/include`
- [Core Hub](https://github.com/rizinorg/rizin/tree/dev/librz/core): orchestrator · Central coordinator for open/seek/analyze/debug/search/commands. · `librz/core`
- [IO Layer](https://github.com/rizinorg/rizin/tree/dev/librz/io): byte access · File, memory, cache, map, remote, and transport abstractions. · `librz/io`
- [Binary Loader](https://github.com/rizinorg/rizin/tree/dev/librz/bin): format parser · Container and executable format identification and parsing. · `librz/bin`
- [Arch Engine](https://github.com/rizinorg/rizin/tree/dev/librz/arch): analysis framework · Architecture framework plus disassembly, semantics, conventions, and platform profiles. · `librz/arch`
- [ESIL](https://github.com/rizinorg/rizin/tree/dev/librz/arch/esil): semantic eval · ESIL emulation-style semantics, tracing, and analysis support. · `librz/arch/esil`
- [RZIL](https://github.com/rizinorg/rizin/tree/dev/librz/il): intermediate IR · Structured intermediate representation with validation, export, graphing, and VM evaluation. · `librz/il`
- [Debug Core](https://github.com/rizinorg/rizin/tree/dev/librz/debug): debug subsystem · Breakpoints, registers, traces, sessions, signals, and native backends. · `librz/debug`
- [Console](https://github.com/rizinorg/rizin/tree/dev/librz/cons): output/input · Formatting, prompts, paging, canvases, and terminal interaction helpers. · `librz/cons`
- [Search](https://github.com/rizinorg/rizin/tree/dev/librz/search): match engine · Byte, string, regexp, entropy, hash, magic, and value searches. · `librz/search`
- [Types](https://github.com/rizinorg/rizin/tree/dev/librz/type): type system · Type definitions, parsing, formatting, and serialization. · `librz/type`
- [Registers](https://github.com/rizinorg/rizin/tree/dev/librz/reg): profiles · Register arenas, profiles, and calling/ABI metadata. · `librz/reg`
- **State DB**: flags/projects · Flags, marks, projects, seek history, and serialized user state.
- [Cmd Router](https://github.com/rizinorg/rizin/tree/dev/librz/core/cmd): interactive commands · Command parser, descriptors, and dispatch into core operations. · `librz/core/cmd`
- [TUI](https://github.com/rizinorg/rizin/tree/dev/librz/core/tui): visual interface · Visual panels, HUDs, and interactive screen modes. · `librz/core/tui`

### Frontends

Thin command-line entry points and interactive UI layer.

- [CLI Tools](https://github.com/rizinorg/rizin/tree/dev/librz/main): frontends · Thin executables such as rizin, rz-bin, rz-asm, rz-hash, and friends. · `librz/main`
- [Shell Parser](https://github.com/rizinorg/rizin/tree/dev/subprojects/rizin-shell-parser): command grammar · Interactive command-language parser used by the console frontends. · `subprojects/rizin-shell-parser`

### Plugins & Data

Plugin backends and declarative tables that drive formats, CPUs, and profiles.

- **Plugins**: backend modules · Format, architecture, debug, IO, and language plugins loaded by core.
- **Data Tables**: sdb metadata · Declarative opcode, syscall, ABI, type, and format tables.
- [Remote IO](https://github.com/rizinorg/rizin/tree/dev/librz/socket): network transport · Socket, HTTP, process, and rzpipe-style automation transports. · `librz/socket`
- [Crypto](https://github.com/rizinorg/rizin/tree/dev/librz/crypto): encoding primitives · Hashes, ciphers, and encoding helpers used across analysis and search. · `librz/crypto`

### Support

Build, packaging, and repository infrastructure.

- [Build System](https://github.com/rizinorg/rizin/blob/dev/meson.build): meson build · Meson, wraps, subprojects, packaging, and cross-platform build orchestration. · `meson.build`
- [Tests](https://github.com/rizinorg/rizin/tree/dev/test): verification · Unit, integration, and database-backed regression coverage. · `test`

## Connections

- CLI Tools → Cmd Router: dispatches · CLI entrypoints hand commands to the router.
- CLI Tools → Core Hub: drives · Tools are thin wrappers around core workflows.
- Cmd Router → Core Hub: invokes · Command parsing resolves to core operations.
- TUI → Cmd Router: issues · Visual modes route actions through commands.
- Core Hub → IO Layer: reads · Core opens sources through the IO abstraction.
- Core Hub → Binary Loader: loads · Core delegates binary identification and parsing.
- Core Hub → Arch Engine: analyzes · Core asks architecture services for disassembly and analysis.
- Core Hub → Debug Core: debugs · Core coordinates sessions, breakpoints, and process control.
- Core Hub → Search: searches · Core exposes search workflows over the loaded target.
- Core Hub → Types: types · Core uses the type system for inspection and formatting.
- Core Hub → Registers: profiles · Core consults register and ABI profiles.
- Core Hub → State DB: persists · Core stores user state such as flags, marks, and projects.
- Core Hub → Crypto: uses · Core invokes hashing and encoding helpers.
- Arch Engine → ESIL: semantics · Architecture analysis can lower to ESIL semantics.
- Arch Engine → RZIL: lowers · Architecture analysis can emit RZIL.
- Binary Loader → Data Tables: consults · Binary parsing relies on declarative metadata tables.
- Arch Engine → Data Tables: consults · ISA and ABI behavior are largely table-driven.
- Debug Core → Remote IO: transports · Remote debugging and automation share socket/process transports.
- IO Layer → Remote IO: wraps · IO includes remote and debug-oriented backends.
- Shell Parser → Cmd Router: parses · Interactive shell grammar feeds the command layer.
- Public API → Core Hub: exports · Public headers expose the central API surface.
- Public API → IO Layer: exports · Public headers expose IO interfaces.
- Public API → Arch Engine: exports · Public headers expose analysis and architecture interfaces.
- Public API → Debug Core: exports · Public headers expose debugging interfaces.
- Public API → RZIL: exports · Public headers expose RZIL interfaces.
- Plugins → Arch Engine: extends · Architecture plugins provide ISA-specific behavior.
- Plugins → Binary Loader: extends · Binary plugins add format support.
- Plugins → Debug Core: extends · Debug plugins provide platform backends.
- Plugins → IO Layer: extends · IO plugins add transport and source support.
- Build System → Plugins: assembles · Build system wires in plugins and subprojects.
- Build System → CLI Tools: produces · Build system produces the thin executables.
- Tests → Core Hub: verifies · Integration and regression tests exercise core flows.
- Tests → Binary Loader: verifies · Format fixtures validate binary loading.
- Tests → Arch Engine: verifies · Assembly and analysis fixtures validate ISA support.
- Tests → Debug Core: verifies · Debug fixtures validate backend behavior.
- Tests → Cmd Router: verifies · Command database tests validate interactive flows.
