# zyantific/zasm architecture

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

- Interactive diagram: https://gitdiagram.com/zyantific/zasm
- Repository: https://github.com/zyantific/zasm

## Overview

##### Project type and purpose
- Zasm is a C++ library for assembling, decoding, formatting, and serializing x86-64 machine code.
- It sits on top of the Zydis decoder/encoder backend to provide a higher-level API (Program, Assembler, Serializer, Decoder).

##### File structure
- Top-level directories:
- zasm/include & zasm/src: the core library modules
- examples: client code demonstrating usage
- benchmark: performance tests using the library
- tests: unit tests exercising all features
- thirdparty: build/tooling support (cmkr/CMake)
- Within zasm/include & src, submodules reflect architectural areas:
- core: streams, error handling, pools, strong types
- decoder: binary→Instruction
- encoder/formatter: Instruction→binary text/format
- program: node container (instructions, labels, sections)
- serialization: converting Program nodes into flat binary
- x86: assembler macros, register definitions, emitter

##### Extract insights from README
- Main API abstractions: Program, Assembler, Serializer, Decoder
- Design goals: lightweight, node-based code manipulation, accurate operand/flag info
- Builder uses CMake + cmkr for build configuration
- Examples & tests demonstrate all paths

##### Main components and their interactions
- Clients (examples, benchmarks, tests) → Zasm API
- Zasm API layers:
a. Program: holds node list (instructions, labels, data, sections)
b. Assembler: emits nodes into Program (uses x86 assembler)
c. Decoder: uses Zydis to parse existing binary into Instruction nodes
d. Serializer: walks Program nodes, emits raw binary, produces metadata (label addresses, relocations)
- Core utilities (memory/file streams, stringpool, objectpool, error handling) support all layers
- Encoder/formatter: depth of instruction encoding & textual representation
- x86 module: CPU-specific encodings, mnemonics, register definitions, emitter logic
- External dependency: Zydis (third-party library)

##### Architectural patterns & design principles
- Node-based doubly linked list (Program) allows insertion, removal, reordering
- Separation of concerns:
- decoding (binary→node) vs. assembly (API calls→node)
- serialization (node→binary) vs. formatting (node→text)
- Factory/generator pattern in Assembler (generated member functions per instruction)
- Strongly typed operands & flags

##### Detail level
- Don’t just show “Library”—split it into its submodules (Program, Assembler, Decoder, Serializer).
- That Program is the central node container.
- How x86-specific code sits under Assembler/Encoder.
- External Zydis dependency both in Decoder and Encoder phases.
- Lifecycles: decode → transform → serialize.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        Examples["Examples"]:::client
        Benchmarks["Benchmarks"]:::client
        Tests["Tests"]:::client
    end

    %% Zasm API Layer
    subgraph "Zasm API Layer"
        Program["Program"]:::api
        Assembler["Assembler"]:::api
        Decoder["Decoder"]:::api
        Serializer["Serializer"]:::api
    end

    %% Core Utilities
    subgraph "Core Utilities"
        CoreUtils["Core Utilities"]:::core
    end

    %% Encoder & Formatter
    subgraph "Encoder & Formatter"
        Encoder["Encoder"]:::x86
        Formatter["Formatter"]:::x86
    end

    %% x86 Specific Module
    subgraph "x86 Specific"
        X86Module["x86 Module"]:::x86
    end

    %% External Backend
    Zydis["Zydis"]:::external

    %% Build System
    subgraph "Build System"
        CMakeRoot["CMake Files"]:::build
        CMakeTP["Thirdparty CMake"]:::build
    end

    %% Relationships
    Examples -->|uses Assembler| Assembler
    Examples -->|uses Decoder| Decoder
    Examples -->|uses Serializer| Serializer
    Benchmarks -->|uses Assembler| Assembler
    Benchmarks -->|uses Decoder| Decoder
    Benchmarks -->|uses Serializer| Serializer
    Tests -->|uses Assembler| Assembler
    Tests -->|uses Decoder| Decoder
    Tests -->|uses Serializer| Serializer

    Assembler -->|emits nodes into| Program
    Decoder -->|parses binary into| Program
    Program -->|provides nodes to| Serializer
    Program -->|provides nodes to| Formatter

    Serializer -->|delegates encoding to| Zydis
    Decoder -->|delegates parsing to| Zydis

    Serializer -->|uses| Encoder
    Formatter -->|formats| Program

    Assembler -->|uses| X86Module
    Encoder -->|uses| X86Module

    %% Core dependencies
    Assembler -.->|depends on| CoreUtils
    Decoder -.->|depends on| CoreUtils
    Serializer -.->|depends on| CoreUtils
    Program -.->|depends on| CoreUtils
    Encoder -.->|depends on| CoreUtils
    Formatter -.->|depends on| CoreUtils
    X86Module -.->|depends on| CoreUtils

    %% Build system integration
    CMakeRoot -->|builds library| Program
    CMakeRoot -->|builds library| Assembler
    CMakeRoot -->|builds library| Decoder
    CMakeRoot -->|builds library| Serializer
    CMakeRoot -->|builds library| Encoder
    CMakeRoot -->|builds library| Formatter
    CMakeTP -->|includes tooling| CMakeRoot

    %% Click Events
    click Program "https://github.com/zyantific/zasm/tree/master/zasm/include/zasm/program/"
    click Program "https://github.com/zyantific/zasm/tree/master/zasm/src/zasm/src/program/"
    click Assembler "https://github.com/zyantific/zasm/blob/master/zasm/include/zasm/x86/assembler.hpp"
    click Assembler "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/x86/x86.assembler.cpp"
    click Decoder "https://github.com/zyantific/zasm/blob/master/zasm/include/zasm/decoder/decoder.hpp"
    click Decoder "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/decoder/decoder.cpp"
    click Serializer "https://github.com/zyantific/zasm/blob/master/zasm/include/zasm/serialization/serializer.hpp"
    click Serializer "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/serialization/serializer.cpp"
    click Encoder "https://github.com/zyantific/zasm/blob/master/zasm/include/zasm/encoder/encoder.hpp"
    click Encoder "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/encoder/encoder.cpp"
    click Encoder "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/encoder/encoder.context.hpp"
    click Formatter "https://github.com/zyantific/zasm/blob/master/zasm/include/zasm/formatter/formatter.hpp"
    click Formatter "https://github.com/zyantific/zasm/blob/master/zasm/src/zasm/src/formatter/formatter.cpp"
    click CoreUtils "https://github.com/zyantific/zasm/tree/master/zasm/include/zasm/core/"
    click CoreUtils "https://github.com/zyantific/zasm/tree/master/zasm/src/zasm/src/core/"
    click X86Module "https://github.com/zyantific/zasm/tree/master/zasm/include/zasm/x86/"
    click X86Module "https://github.com/zyantific/zasm/tree/master/zasm/src/zasm/src/x86/"
    click CMakeRoot "https://github.com/zyantific/zasm/blob/master/CMakeLists.txt"
    click CMakeTP "https://github.com/zyantific/zasm/blob/master/thirdparty/CMakeLists.txt"

    %% Styles
    classDef client fill:#ccf,stroke:#333,stroke-width:1px
    classDef api fill:#bbf,stroke:#333,stroke-width:1px
    classDef core fill:#bfb,stroke:#333,stroke-width:1px,stroke-dasharray:5 5
    classDef x86 fill:#fdb,stroke:#333,stroke-width:1px
    classDef external fill:#ddd,stroke:#333,stroke-width:1px
    classDef build fill:#dcb,stroke:#333,stroke-width:1px
```
