# srlabs/ziggy architecture

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

- Interactive diagram: https://gitdiagram.com/srlabs/ziggy
- Repository: https://github.com/srlabs/ziggy

## Overview

##### Main Components
- CLI / Command Interface: The central entry point is the “cargo ziggy” tool. This is implemented in the src/bin/cargo-ziggy directory and is responsible for parsing user commands (build, fuzz, run, minimize, cover, plot, add-seeds, triage, etc.).
- Core Fuzzer Manager / Engine: The heart of the system (likely implemented in src/lib.rs and used by the binary) manages launching the various fuzzing processes concurrently. It coordinates parallel execution, shared corpus handling, and integration with tools like AFL++ and Honggfuzz.
- Fuzzer Wrappers: There are dedicated modules or subcommands (e.g., fuzz.rs, coverage.rs, minimize.rs, triage.rs) that handle specific functionality. Each of these should be represented as a component that interfaces with the manager.
- Shared Corpus & Output Management: As described in the README, after fuzzing the output directory is created with separate subdirectories (corpus, crashes, logs, afl, honggfuzz, queue). Represent this as a storage component that interacts with the processes.
- Examples and Integration: The “examples” directory (with arbitrary, asan, and url examples) demonstrates how to use “ziggy” both as a standalone tool (via CLI) and as a dependency (using the fuzz! macro). Include these as peripheral integrations that showcase the extensibility.

##### Relationships and Interactions
- The tool’s internal logging mechanism (activated by the RUST_LOG environment variable) passes information back to the user. Include a logging/monitoring component.
- The examples act as usage demonstrations; while not a runtime component, they indicate how the “ziggy” library is embedded in other projects.

##### Architectural Patterns and Design Principles
- Modularity: Each command/subcommand (build, fuzz, cover, etc.) is implemented in its dedicated Rust file. This reflects a modular, single-responsibility design.
- Parallel Process Management: The engine is designed to run different fuzzers concurrently using shared resources – an important concurrency pattern.
- Separation of Concerns: The separation between the CLI (user interaction), fuzzer management (process spawning and coordination), and output management (corpus and logs) is clearly indicated.

##### Relevant Technologies, Frameworks, or Libraries
- Rust/Cargo: The whole project is implemented in Rust.
- Underlying fuzzers: AFL++, Honggfuzz (and the potential for LibAFL integration) are explicitly mentioned.
- CI Integration: The presence of a GitHub Actions workflow (.github/workflows/ci.yml) indicates continuous integration support.
- Coverage Tools: grcov is mentioned for generating coverage reports.
- Notification hooks (bash notification for crashes) may also be noted.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["CLI: cargo ziggy (src/bin/cargo-ziggy)"]:::cli
    CORE["Core Fuzzer Manager (src/lib.rs)"]:::core
    LOG["Logging/Monitoring"]:::log

    CLI --> CORE
    CORE --> LOG

    subgraph "Fuzzer Subcommands"
        BUILD["Build (src/bin/cargo-ziggy/build.rs)"]:::sub
        FUZZ["Fuzz (src/bin/cargo-ziggy/fuzz.rs)"]:::sub
        RUN["Run (src/bin/cargo-ziggy/run.rs)"]:::sub
        MINIMIZE["Minimize (src/bin/cargo-ziggy/minimize.rs)"]:::sub
        COVERAGE["Coverage (src/bin/cargo-ziggy/coverage.rs)"]:::sub
        PLOT["Plot (src/bin/cargo-ziggy/plot.rs)"]:::sub
        TRIAGE["Triage (src/bin/cargo-ziggy/triage.rs)"]:::sub
        ADDSEEDS["Add-Seeds (src/bin/cargo-ziggy/add_seeds.rs)"]:::sub
    end

    CORE --> BUILD
    CORE --> FUZZ
    CORE --> RUN
    CORE --> MINIMIZE
    CORE --> COVERAGE
    CORE --> PLOT
    CORE --> TRIAGE
    CORE --> ADDSEEDS

    OUTPUT["Output Management: corpus, crashes, logs, afl, honggfuzz, queue"]:::output
    BUILD --> OUTPUT
    FUZZ --> OUTPUT
    RUN --> OUTPUT
    MINIMIZE --> OUTPUT
    COVERAGE --> OUTPUT
    PLOT --> OUTPUT
    TRIAGE --> OUTPUT
    ADDSEEDS --> OUTPUT

    EXAMPLES["Examples & Integration (examples/arbitrary, examples/asan, examples/url)"]:::examples
    OUTPUT --- EXAMPLES

    CI["CI Integration (.github/workflows/ci.yml)"]:::ci
    CI --- CLI

    click CLI "https://github.com/srlabs/ziggy/tree/main/src/bin/cargo-ziggy"
    click CORE "https://github.com/srlabs/ziggy/blob/main/src/lib.rs"
    click BUILD "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/build.rs"
    click FUZZ "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/fuzz.rs"
    click RUN "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/run.rs"
    click MINIMIZE "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/minimize.rs"
    click COVERAGE "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/coverage.rs"
    click PLOT "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/plot.rs"
    click TRIAGE "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/triage.rs"
    click ADDSEEDS "https://github.com/srlabs/ziggy/blob/main/src/bin/cargo-ziggy/add_seeds.rs"
    click CI "https://github.com/srlabs/ziggy/blob/main/.github/workflows/ci.yml"
    click EXAMPLES "https://github.com/srlabs/ziggy/tree/main/examples"

    classDef cli fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef core fill:#C1E1C1,stroke:#000,stroke-width:2px;
    classDef sub fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef output fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef examples fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef log fill:#F5DEB3,stroke:#000,stroke-width:2px;
```
