# clearbluejar/ghidriff architecture

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

- Interactive diagram: https://gitdiagram.com/clearbluejar/ghidriff
- Repository: https://github.com/clearbluejar/ghidriff

## Overview

##### Project type and purpose
- This is an open-source, Python-based **command-line binary diffing engine** named “ghidriff.”
- It orchestrates Ghidra headless analysis via JPype/PyGhidra, matches functions between two binaries, and emits JSON, Markdown, and optional HTML diffs.
- It also includes a static documentation/web site (Docusaurus) under `www/`.

##### File structure
- Top-level Python package (`ghidriff/`) holds core logic:
- `__main__.py` (CLI entrypoint)
- `ghidra_diff_engine.py` (base class with template workflow steps)
- `simple_diff.py`, `structural_graph_diff.py`, `version_tracking_diff.py` (engine implementations)
- `correlators.py` (function-matching algorithms), `markdown.py` (Markdown renderer), `parser.py`, `utils.py`
- `tests/` validates the package.
- `setup.py`/`setup.cfg` define packaging and entrypoint.
- `Dockerfile` and `.devcontainer/` support containerized dev and CI.
- `www/` contains a standalone Docusaurus-based documentation site.

##### Key insights from the README
- **Architecture**: A template-method pattern (`GhidraDiffEngine`) that implements common Ghidra headless steps (project creation, import, analysis) and delegates `find_matches()` to pluggable implementations.
- **Workflow**:
1. CLI parses arguments →
2. Instantiate chosen Engine (Simple, Graph, VersionTracking) →
3. Launch Ghidra headless via JPype →
4. Import/analyze binaries →
5. Run correlators to match functions →
6. Post-process and render outputs (JSON, Markdown, HTML).
- **External services**: Symbol servers (MSDL, Chromium, Mozilla, Intel, NVIDIA, AMD) for PDB lookups.

- **CLI Interface** (Rectangle, e.g., blue)
- **Engine Core** (`GhidraDiffEngine` base class)
- **Engine Implementations** (three plugin classes)
- **Correlators** module (function-matching strategies)
- **Ghidra Integration** (JPype/PyGhidra bridge + headless Java process)
- **Symbol Server Client** (HTTP clients to external symbol servers)
- **Output Renderers** (Markdown, HTML side-by-side)
- **Data Stores** (JSON output directory, `ghidra_projects`, symbols cache)
- **Testing Suite** (`tests/`)
- **Documentation Site** (Docusaurus under `www/`)

1. **User** → runs `ghidriff` (CLI)
2. **CLI** → instantiates and configures **Engine Core**
3. **Engine Core** → spawns **Ghidra headless** (via JPype)
4. **Ghidra** → imports/analyzes binaries → writes to **Ghidra Project** folder
5. **Engine Core** → invokes **Engine Implementation** (`find_matches`)
6. **Engine Implementation** ↔ uses **Correlators** to compute function matches
7. **Engine Core** → calls **Output Renderers** → writes JSON, Markdown, optional HTML to disk
8. **Engine Core** → interacts with **Symbol Server Client** to fetch PDBs into local cache
9. **Documentation Site** is independent; it reads Markdown examples under `www/diffs` and `www/docs` for publication.

c. Architectural patterns and principles:
- **Template Method**: `GhidraDiffEngine` defines the diffing workflow skeleton.
- **Plugin/Strategy**: Diff algorithms (`SimpleDiff`, etc.) and correlators are swappable.
- **Separation of Concerns**: CLI parsing, engine workflow, algorithmic matching, and output rendering are each in their own modules.
- **Infrastructure as Code**: Devcontainer and GitHub Actions for CI, Docker for packaging.

d. Key technologies/frameworks:
- **Python 3** with `pyghidra` and `jpype`
- **Ghidra Headless** (Java)
- **Docusaurus** (React/Node) for docs site
- **Docker** / **Devcontainer** / **GitHub Actions** for CI/CD
- **HTTP symbol servers** for PDB retrieval

##### Diagramming Recommendations
- **Labels**: Clearly name each module or external service.
- Core modules (blue rectangles)
- Plugins/strategies (light green)
- External systems (gray clouds)
- Documentation site (purple)

##### Capturing Essential Elements
- How a new diff engine plugs into the base class.
- Ghidra headless subprocess and its artifacts (project files).
- Symbol fetching as a side-flow into the analysis step.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    User["User"]:::external
    CLI["CLI Interface"]:::core
    EngineCore["GhidraDiffEngine (Engine Core)"]:::core
    subgraph "Engine Implementations"
        SimpleDiff["SimpleDiffEngine"]:::plugin
        GraphDiff["StructuralGraphDiffEngine"]:::plugin
        VersionDiff["VersionTrackingDiffEngine"]:::plugin
    end
    subgraph "Correlators Module"
        Correlators["correlators.py"]:::plugin
        DecompCorrelator["DecompilerCorrelator"]:::plugin
        ImpliedMatches["ImpliedMatchesHelper"]:::plugin
        BSIM["BSIM Interface"]:::plugin
    end
    Ghidra["Ghidra Headless\n(via JPype/PyGhidra)"]:::external
    SymbolClient["Symbol Server Client\n(HTTP PDB Fetch)"]:::external
    subgraph "Data Stores / Caches"
        GhidaProj["Ghidra Projects\nDirectory"]:::datastore
        SymCache["Symbol Cache"]:::datastore
        Outputs["Output Directory\n(JSON, Markdown, HTML)"]:::datastore
    end
    OutputsRenderer["Output Renderers\n(Markdown, HTML)"]:::core
    TestSuite["Test Suite\n(tests/)"]:::infra
    CI["CI/CD & Dev Container\n(.devcontainer/, Dockerfile)"]:::infra
    DocsSite["Documentation Site\n(www/)"]:::docs

    %% Flow
    User -->|"runs ghidriff"| CLI
    CLI -->|"instantiates"| EngineCore
    EngineCore -->|"spawns via JPype"| Ghidra
    Ghidra -->|"writes projects"| GhidaProj
    EngineCore -->|"selects"| SimpleDiff
    EngineCore -->|"selects"| GraphDiff
    EngineCore -->|"selects"| VersionDiff
    SimpleDiff <-->|"uses"| Correlators
    GraphDiff <-->|"uses"| Correlators
    VersionDiff <-->|"uses"| Correlators
    Correlators <-->|"calls helpers"| DecompCorrelator
    Correlators <-->|"calls helpers"| ImpliedMatches
    Correlators <-->|"abstraction"| BSIM
    EngineCore -->|"fetch symbols"| SymbolClient
    SymbolClient -->|"stores"| SymCache
    EngineCore -->|"calls"| OutputsRenderer
    OutputsRenderer -->|"writes"| Outputs
    Outputs -->|"consumed by"| DocsSite

    %% Additional components
    TestSuite ---|"validates"| EngineCore
    TestSuite ---|"validates"| SimpleDiff
    TestSuite ---|"validates"| Correlators
    CI ---|"builds/tests"| TestSuite
    CI ---|"provides"| SymCache
    CI ---|"container config"| Ghidra

    %% Click Events
    click CLI "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/__main__.py"
    click EngineCore "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/ghidra_diff_engine.py"
    click SimpleDiff "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/simple_diff.py"
    click GraphDiff "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/structural_graph_diff.py"
    click VersionDiff "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/version_tracking_diff.py"
    click Correlators "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/correlators.py"
    click DecompCorrelator "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/decomp_correlate.py"
    click ImpliedMatches "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/implied_matches.py"
    click BSIM "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/bsim.py"
    click OutputsRenderer "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/markdown.py"
    click Parser "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/parser.py"
    click Utils "https://github.com/clearbluejar/ghidriff/blob/main/ghidriff/utils.py"
    click Setup "https://github.com/clearbluejar/ghidriff/blob/main/setup.py"
    click Tests "https://github.com/clearbluejar/ghidriff/tree/main/tests/"
    click CI "https://github.com/clearbluejar/ghidriff/tree/main/ .devcontainer/"
    click CI "https://github.com/clearbluejar/ghidriff/tree/main/Dockerfile"
    click DocsSite "https://github.com/clearbluejar/ghidriff/tree/main/www/"

    %% Styles
    classDef core fill:#D0E1F9,stroke:#333,stroke-width:1px
    classDef plugin fill:#DAF5D0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef docs fill:#E3D0F3,stroke:#333,stroke-width:1px
    classDef infra fill:#E8E8E8,stroke:#333,stroke-width:1px
```
