# gumtreediff/gumtree architecture

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

- Interactive diagram: https://gitdiagram.com/gumtreediff/gumtree
- Repository: https://github.com/gumtreediff/gumtree

## Overview

##### Project type and purpose
- This is a multi-module Java library / tool (“GumTree”) for syntax-aware AST differencing. It provides:
- A core diff engine (matching, actions)
- Language-specific tree generators (plugins wrapping ANTLR, JDT, srcML, Tree-sitter, etc.)
- User interfaces (CLI client, Swing- and web-based diff viewer)
- Benchmarking harness
- Docker packaging and documentation

##### File structure
- Root: settings.gradle, build.gradle, .github (CI), docker, doc, dist, benchmark, buildSrc (Gradle scripts)
- Subprojects (each with its own build.gradle):
- core – the diff engine: packages for tree model, matchers (heuristic & optimal), action generators, IO utilities, tests
- gen.* – one subproject per language or input format (antlr3, antlr4, css, javaparser, jdt, js, json, srcml, treesitter-ng, xml, yaml). Each exposes a TreeGenerator plugin.
- client – the CLI front-end: parse arguments, invoke tree gen, core diff, print edit script
- client.diff – the GUI/web diff viewer: Swing panels + embedded Monaco browser widgets
- benchmark – dataset runners invoking the CLI on datasets, measuring performance
- docker – Dockerfile to containerize the CLI or server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Source and artifacts
    SRC["Source Code File"]:::doc
    AST["AST Tree"]:::cyl
    EDIT["EditScript (Diff Result)"]:::doc

    %% Parser Plugins
    subgraph "Parser Plugins" 
        class PP parser
        Antlr3["ANTLR3 Plugin"] 
        Antlr4["ANTLR4 Plugin"]
        CSSP["CSS Plugin"]
        JP["JavaParser Plugin"]
        JDT["JDT Plugin"]
        JS["JavaScript (Rhino) Plugin"]
        JSONP["JSON Plugin"]
        srcML["srcML Plugin"]
        TSNG["Tree-sitter-NG Plugin"]
        XMLP["XML Plugin"]
        YAMLP["YAML Plugin"]
    end

    %% Core Engine
    subgraph "Core Engine"
        class CE coreEngine
        TM["Tree Model"]
        Matcher["Matcher Subsystem"]
        Heu["Heuristic Matcher"]
        Opt["Optimal Matcher"]
        AG["ActionGenerator Subsystem"]
        IO["IO Utilities"]
        PR["Plugin Registration & Interfaces"]
    end

    %% Client Interfaces
    subgraph "Client Interfaces"
        class CI client
        CLI["CLI Client"]
        Disp["Argument Parsing & Dispatch"]
        GUI["GUI/Web Diff Viewer"]
        Swing["Swing Panels"]
        Web["Monaco & HTML Viewer"]
    end

    %% Benchmark & Packaging
    subgraph "Benchmark & Packaging"
        class BP packaging
        BH["Benchmark Harness"]
        GRADLE["Gradle Build & Config"]
        GSCRIPTS["Custom Gradle Scripts"]
        DOCKER["Docker Container"]:::cyl
    end

    %% Data Flow
    SRC -->|parses via| Antlr3
    SRC --> Antlr4
    SRC --> CSSP
    SRC --> JP
    SRC --> JDT
    SRC --> JS
    SRC --> JSONP
    SRC --> srcML
    SRC --> TSNG
    SRC --> XMLP
    SRC --> YAMLP
    Antlr3 --> AST
    Antlr4 --> AST
    CSSP --> AST
    JP --> AST
    JDT --> AST
    JS --> AST
    JSONP --> AST
    srcML --> AST
    TSNG --> AST
    XMLP --> AST
    YAMLP --> AST

    AST -->|to| TM
    TM --> Matcher
    Matcher --> Heu
    Matcher --> Opt
    Matcher --> AG
    AG --> IO
    AG --> EDIT

    EDIT -->|output to| CLI
    CLI -->|uses| Disp
    EDIT --> GUI
    GUI --> Swing
    GUI --> Web

    BH -->|invokes| CLI
    BH -->|collects metrics| EDIT
    GRADLE -->|builds modules| PP
    GRADLE -->|builds modules| CE
    GRADLE -->|builds modules| CI
    GRADLE -->|runs| BH
    GSCRIPTS -->|assist build| GRADLE
    DOCKER -->|packages| CLI

    %% Click Events
    click TM "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/tree"
    click Matcher "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/matchers"
    click Opt "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/matchers/optimal"
    click Heu "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/matchers/heuristic"
    click AG "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/actions"
    click IO "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/io"
    click PR "https://github.com/gumtreediff/gumtree/tree/main/core/src/main/java/com/github/gumtreediff/gen"
    click CLI "https://github.com/gumtreediff/gumtree/blob/main/client/src/main/java/com/github/gumtreediff/client/Client.java"
    click Disp "https://github.com/gumtreediff/gumtree/blob/main/client/src/main/java/com/github/gumtreediff/client/Clients.java"
    click GUI "https://github.com/gumtreediff/gumtree/tree/main/client.diff/src/main/java/com/github/gumtreediff/client/diff"
    click Swing "https://github.com/gumtreediff/gumtree/tree/main/client.diff/src/main/java/com/github/gumtreediff/client/diff/swingdiff"
    click Web "https://github.com/gumtreediff/gumtree/tree/main/client.diff/src/main/java/com/github/gumtreediff/client/diff/webdiff"
    click BH "https://github.com/gumtreediff/gumtree/blob/main/benchmark/src/main/java/com/github/gumtree/benchmark/RunOnDataset.java"
    click DOCKER "https://github.com/gumtreediff/gumtree/tree/main/docker/Dockerfile"
    click GRADLE "https://github.com/gumtreediff/gumtree/blob/main/settings.gradle"
    click GSCRIPTS "https://github.com/gumtreediff/gumtree/tree/main/buildSrc/src/main/groovy"
    click Antlr3 "https://github.com/gumtreediff/gumtree/tree/main/gen.antlr3/src/main/java/com/github/gumtreediff/gen/antlr3"
    click Antlr4 "https://github.com/gumtreediff/gumtree/tree/main/gen.antlr4/src/main/java/com/github/gumtreediff/gen/antlr4"
    click CSSP "https://github.com/gumtreediff/gumtree/tree/main/gen.css/src/main/java/com/github/gumtreediff/gen/css"
    click JP "https://github.com/gumtreediff/gumtree/tree/main/gen.javaparser/src/main/java/com/github/gumtreediff/gen/javaparser"
    click JDT "https://github.com/gumtreediff/gumtree/tree/main/gen.jdt/src/main/java/com/github/gumtreediff/gen/jdt"
    click JS "https://github.com/gumtreediff/gumtree/tree/main/gen.js/src/main/java/com/github/gumtreediff/gen/js"
    click JSONP "https://github.com/gumtreediff/gumtree/tree/main/gen.json/src/main/java/com/github/gumtreediff/gen/json"
    click srcML "https://github.com/gumtreediff/gumtree/tree/main/gen.srcml/src/main/java/com/github/gumtreediff/gen/srcml"
    click TSNG "https://github.com/gumtreediff/gumtree/tree/main/gen.treesitter-ng/src/main/java/com/github/gumtreediff/gen/treesitterng"
    click XMLP "https://github.com/gumtreediff/gumtree/blob/main/gen.xml/src/main/java/com/github/gumtreediff/gen/json/XmlTreeGenerator.java"
    click YAMLP "https://github.com/gumtreediff/gumtree/tree/main/gen.yaml/src/main/java/com/github/gumtreediff/gen/yaml"

    %% Styles
    classDef coreEngine fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef parser fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef client fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef packaging fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef cyl stroke:#000,stroke-dasharray: 4 2
    classDef doc fill:#ffffff,stroke:#000000,stroke-dasharray: 2 2,color:#000
    class PP parser
    class CE coreEngine
    class CI client
    class BP packaging
```
