# matias-gonz/abstraktor architecture

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

- Interactive diagram: https://gitdiagram.com/matias-gonz/abstraktor
- Repository: https://github.com/matias-gonz/abstraktor

## Overview

##### Project Type and Purpose
- Abstraktor is a Rust-based CLI tool for validating distributed protocol implementations by generating enabling-preserving abstractions (EPAs).
- It is structured as a command-line orchestrator (“CLI Tool”) that invokes:
a. An LLVM-based Instrumenter to rewrite target binaries,
b. A Mallory fuzzing engine extension to collect runtime state,
c. An EPA Generator to build abstractions from the collected data.

##### File Structure Analysis
- Top-level Cargo.toml and src/: core Rust CLI code lives under src/
- src/main.rs – entry point and argument parsing using clap or similar.
- src/commands/ – subcommands: prepare-binary (instrument), run-mallory, generate-epas, get-targets.
- src/model/instrumentor.rs – high-level Rust API for driving LLVM instrumentation.
- llvm/ directory encapsulates the C-based instrumenter users:
- llvm/src/ and llvm/include/ – LLVM pass and runtime support.
- llvm/rustc-demangle/ – helper crate for symbol demangling.
- tests/ – integration fixtures demonstrating instrumentation workflows.

##### README Insights
- Describes a 4-stage workflow: annotate source, prepare-binary, run-mallory, generate-epas.

##### Main Architectural Components
a. Developer/Client – annotates code and invokes the CLI.
b. CLI Tool (Rust) – src/main.rs + src/commands/ modules.
c. LLVM Instrumenter – C and Rust wrapper under llvm/ + src/model/instrumentor.
d. Mallory Extension – external fuzzing engine invoked by run-mallory command.
e. EPA Generator – part of the CLI’s generate-epas command, implemented in Rust.
f. File-system & Test harness – integration tests drive the end-to-end.

##### Component Relationships and Data Flow
- The Developer invokes the CLI.
- prepare-binary → CLI calls the Instrumenter module → loads and runs LLVM passes → outputs an instrumented target binary.
- run-mallory → CLI launches Mallory with the instrumented binary → Mallory fuzzes and emits runtime event logs.
- generate-epas → CLI reads event logs → EPA Generator builds and serializes abstractions.

##### Architectural Patterns and Design Principles
- Modular CLI subcommand pattern: clear separation of concerns by command.
- Adapter pattern: src/model/instrumentor wraps the LLVM/C code under llvm/ to present a Rust API.
- Pipeline/workflow orchestration: linear 4-stage processing, each stage pluggable.
- Test-driven integration: tests/instrument_test demonstrates real code being instrumented and validated.

##### Technologies and Frameworks
- Rust & Cargo – main implementation language and build system.
- LLVM C-API – real code instrumentation.
- Mallory engine – external or vendored fuzzing tool.
- clap or structopt (presumed) for CLI parsing.
- serde/json – for event log and EPA serialization (implied by expected_targets.json).

##### Essential Details to Capture
- Distinguish between compile-time (instrumentation) and runtime (fuzzing, EPA gen).
- Data artifacts at each stage.
- Modular CLI design and the separation of concerns in src/commands/.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Global entities
    Developer["Developer\n(annotates source)"]:::external

    %% CLI Tool subgraph
    subgraph "CLI Tool"
        direction TB
        Main["main.rs\n(src/main.rs)"]:::rustComp
        subgraph "Commands"
            direction TB
            Prepare["prepare-binary\n(src/commands/instrument.rs)"]:::rustComp
            RunMallory["run-mallory\n(src/commands/run_mallory.rs)"]:::rustComp
            Generate["generate-epas\n(src/commands/generate_epas.rs)"]:::rustComp
            GetTargets["get-targets\n(src/commands/get_targets.rs)"]:::rustComp
        end
        subgraph "Model Adapter"
            direction TB
            ModelMod["mod.rs\n(src/model/mod.rs)"]:::rustComp
            InstrAdapter["instrumentor.rs\n(src/model/instrumentor.rs)"]:::rustComp
        end
    end

    %% LLVM Instrumenter subgraph
    subgraph "LLVM Instrumenter"
        direction TB
        LLVMSrc["llvm/src"]:::cComp
        LLVMInc["llvm/include"]:::cComp
        Demangle["rustc-demangle"]:::cComp
    end

    %% External components
    Mallory["Mallory Engine"]:::external

    %% Artifacts
    Binary["Instrumented Binary"]:::artifact
    Logs["Event Logs"]:::artifact
    EPA["EPA Output"]:::artifact

    %% Test Harness
    subgraph "Test Harness"
        direction TB
        Tests["Integration Tests\n(tests/instrument_test/)"]:::external
        JSON["expected_targets.json"]:::artifact
        Csrc["math_utils.c"]:::cComp
    end

    %% Connections
    Developer --> Main
    Main --> Prepare
    Main --> RunMallory
    Main --> Generate
    Main --> GetTargets

    Prepare --> InstrAdapter
    InstrAdapter --> LLVMSrc
    InstrAdapter --> LLVMInc
    InstrAdapter --> Demangle
    LLVMSrc --> Binary
    LLVMInc --> Binary
    Demangle --> Binary

    RunMallory --> Mallory
    Binary --> Mallory
    Mallory --> Logs

    Generate --> Logs
    Generate --> EPA

    Tests --> Main
    Tests --> Binary
    Tests --> JSON
    Tests --> Csrc

    %% Click Events
    click Main "https://github.com/matias-gonz/abstraktor/blob/main/src/main.rs"
    click Prepare "https://github.com/matias-gonz/abstraktor/blob/main/src/commands/instrument.rs"
    click RunMallory "https://github.com/matias-gonz/abstraktor/blob/main/src/commands/run_mallory.rs"
    click Generate "https://github.com/matias-gonz/abstraktor/blob/main/src/commands/generate_epas.rs"
    click GetTargets "https://github.com/matias-gonz/abstraktor/blob/main/src/commands/get_targets.rs"
    click ModelMod "https://github.com/matias-gonz/abstraktor/blob/main/src/model/mod.rs"
    click InstrAdapter "https://github.com/matias-gonz/abstraktor/blob/main/src/model/instrumentor.rs"
    click LLVMSrc "https://github.com/matias-gonz/abstraktor/tree/main/llvm/src/"
    click LLVMInc "https://github.com/matias-gonz/abstraktor/tree/main/llvm/include/"
    click Demangle "https://github.com/matias-gonz/abstraktor/tree/main/llvm/rustc-demangle/"
    click Tests "https://github.com/matias-gonz/abstraktor/tree/main/tests/instrument_test/"
    click JSON "https://github.com/matias-gonz/abstraktor/blob/main/tests/instrument_test/expected_targets.json"
    click Csrc "https://github.com/matias-gonz/abstraktor/blob/main/tests/instrument_test/src/math_utils.c"

    %% Styles
    classDef rustComp fill:#D8E8F9,stroke:#3B6EA5,color:#0A355E
    classDef cComp fill:#FFE4C4,stroke:#B87019,color:#7A3703
    classDef external fill:#E2F9E1,stroke:#2E8B57,color:#004A2F
    classDef artifact fill:#FBE4E1,stroke:#C04D37,color:#7A1E0E
```
