# crytic/medusa architecture

> Architecture diagram of the GitHub repository crytic/medusa, 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/crytic/medusa
- Repository: https://github.com/crytic/medusa

## Overview

##### Main Components
- Fuzzing Engine: This is the core component that includes the modules in the “fuzzing” directory. It handles generating test cases (mutational value generation), invoking test contracts, collecting coverage data, and managing the parallel worker pools.
- Chain Simulation & State Management: Located in the “chain” directory. This component simulates blockchain state and includes support for cheat codes, block context, and state caching. It acts as a virtual environment where smart contract calls are executed.
- Compilation Infrastructure: Found in the “compilation” directory. This part deals with compiling Solidity contracts, parsing ASTs, managing ABI utilities, and bridging against different compilation backends (e.g., solc, crytic_compile).
- CLI / Command Interface: The “cmd” directory carries the entry point (main.go references, cmd/root.go, etc.), which makes the tool accessible via CLI – a key interface for users setting up and executing fuzzing campaigns.
- Logging & Events: The “logging” directory and “events” modules are dedicated to logging the fuzzer’s activity and handling internal event-based hooks. They are essential for debugging, real-time monitoring, or triggering specific actions.
- Utility and Supporting Components: Various utility modules, test utilities (in “utils/testutils”) and configuration files (both in “chain/config” and “fuzzing/config”) provide support across the system.
- Documentation & Tests: The “docs” directory, along with test files distributed in many folders (e.g., chain/state tests, fuzzing tests), offer insights into usage and ensure the software remains reliable.

##### Interactions and Relationships
- The CLI component gathers parameters and options from users and dispatches control to the fuzzer engine.
- The Fuzzing Engine spawns parallel worker routines and communicates with:
- the Chain Simulation component to execute smart contract transactions in a virtual testing environment,
- the Compilation Infrastructure to compile and process smart contract code for fuzz testing.
- The Fuzzing Engine also integrates with Logging and Event systems to report on progress, trigger hooks, and store execution traces.
- Utility packages aid in data conversions, error handling, and configuration management across all these layers.
- The entire process can be initiated or deployed using Docker and CI/CD pipelines defined within GitHub workflows.

##### Architectural Patterns and Principles
- Modular Design: Components like fuzzing, chain simulation, and compilation are clearly isolated, promoting extensibility (for example, the extensible low-level testing API).
- Parallel Processing: Highlight the parallel execution of fuzz test workers—this is a core performance design decision that spans across the fuzzer module.
- Hook/Event Driven Testing: Note the use of hooks and events within the fuzzing engine to allow customized extensions and integration with external systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI / Command Interface"]:::cli
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        FE["Fuzzing Engine"]:::engine
    end

    %% Backend Services
    subgraph "Backend Services"
        CS["Chain Simulation & State Management"]:::chain
        CI["Compilation Infrastructure"]:::compilation
        LE["Logging & Events"]:::logging
    end

    %% Support & Documentation
    subgraph "Support & Documentation"
        UT["Utility & Supporting Components"]:::utility
        DT["Documentation & Tests"]:::docs
    end

    %% Connections between layers
    CLI -->|"dispatches"| FE
    FE -->|"executes-contracts"| CS
    FE -->|"compiles-contracts"| CI
    FE -->|"reports-logs"| LE

    UT -->|"supports"| FE
    UT -->|"supports"| CS
    UT -->|"supports"| CI
    UT -->|"supports"| LE

    CS -->|"feedback-results"| FE
    CI -->|"compiled-output"| FE
    LE -->|"monitoring"| FE
    FE -->|"reports-results"| DT

    %% Click Events
    click CLI "https://github.com/crytic/medusa/tree/master/cmd/"
    click FE "https://github.com/crytic/medusa/tree/master/fuzzing/"
    click CS "https://github.com/crytic/medusa/tree/master/chain/"
    click CI "https://github.com/crytic/medusa/tree/master/compilation/"
    click LE "https://github.com/crytic/medusa/tree/master/logging/"
    click UT "https://github.com/crytic/medusa/tree/master/utils/"
    click DT "https://github.com/crytic/medusa/tree/master/docs/"

    %% Style Classes
    classDef cli fill:#c8f7c5,stroke:#333,stroke-width:2px;
    classDef engine fill:#c0d9f2,stroke:#333,stroke-width:2px;
    classDef chain fill:#f7c8a9,stroke:#333,stroke-width:2px;
    classDef compilation fill:#d9a5f2,stroke:#333,stroke-width:2px;
    classDef logging fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef utility fill:#f2f2f2,stroke:#333,stroke-width:2px;
    classDef docs fill:#fff6a5,stroke:#333,stroke-width:2px;
```
