# noobone123/typeforge architecture

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

- Interactive diagram: https://gitdiagram.com/noobone123/typeforge
- Repository: https://github.com/noobone123/typeforge

## Overview

##### Project Type and Purpose
- TypeForge is a Ghidra extension/tool for binary reverse engineering, specifically aimed at recovering composite data types (structures, unions) from stripped binaries.
- It consists of two main phases:
- Program Analysis phase (implemented in Java as a Ghidra extension)
- LLM-assisted Refinement phase (orchestration in Python scripts)

##### File Structure
- Top-level:
- build.gradle, gradle/…: build configuration for the Java extension
- extension.properties: Ghidra extension metadata
- src/main/java/typeforge: core Java modules
- ghidra_scripts: Java entrypoint scripts for Ghidra (TypeForge.java, GroundTruth.java)
- scripts/: Python orchestration (TypeInference, GroundTruthExtractor, judge/double_elimination)
- data/: configuration files for languages and Sleigh definitions
- lib/: third-party JARs (Jackson, JGraphT, jHeaps)
- Patterns:
- Modular Java packages: analyzer (entrypoints), base (core analysis algorithms: dataflow, graph, node, parallel, passes), utils
- Python wrappers build pipelines around the Java extension
- Demo folder holds sample JSON outputs

##### README Insights
- Two-phase workflow clearly described
- Headless Ghidra invocation via analyzeHeadless + TypeForge.java
- Batch processing via Python scripts
- Demo JSON format, judge scripts for refinement

##### Components
a. Main Components:
1. Ghidra Host
- GUI Mode
- Headless Mode (analyzeHeadless)
2. Java Extension (TypeForge)
- Analyzer package (Generator, ReTyper, TypeAnalyzer)
- Base package:
- dataflow (AccessPoints, ConflictGraph, TypeFlowGraph, Solvers)
- graph (CallGraph, SDGraph)
- node (FunctionNode, DataTypeNode)
- parallel (PrepareFunctionNodeCallback)
- passes (SlidingWindowProcessor, Window)
- Utils (DecompilerHelper, Logging, etc.)
3. Data Store
- data/ languages and Sleigh definitions
- lib/ third-party JARs
4. Python Orchestration Layer
- TypeInference.py (calls Ghidra headless + TypeForge.java)
- GroundTruthExtractor.py
- scripts/judge/double_elimination.py (LLM interactions, refinement)
5. External Services
- LLM API (e.g., OpenAI GPT)
- GitHub (source, issue tracking)
6. Demo & Output
- demo/ JSON result files

b. Relationships & Interactions:
1. User provides stripped binary → Python TypeInference.py
2. TypeInference.py invokes Ghidra headless + TypeForge.java
3. Java extension loads data/ configs and lib jars, runs Program Analysis, emits JSON
4. JSON → Python judge script → LLM API calls for double elimination → refined JSON
5. Final JSON results saved to output directory / demo
6. GroundTruthExtractor similarly wraps GroundTruth.java for debug-info binaries

c. Architectural Patterns & Principles:
- Layered architecture:
- Data/config layer (data/, lib/)
- Core analysis layer (Java packages under src/main/java/typeforge)
- Orchestration layer (Python scripts)
- Pipeline / Workflow pattern: two discrete phases chained by JSON artifacts
- Plugin pattern: implemented as a Ghidra extension, loaded dynamically by Ghidra
- Separation of concerns: analysis engine vs. UI/CLI wrappers vs. refinement logic

d. Technologies & Frameworks:
- Java 11+ (Ghidra 11.0.3 compatibility)
- Ghidra extension APIs
- Gradle build system
- Python 3.x (scripts), PyYAML/config, requests (for LLM calls)
- Third-party libs: Jackson (JSON), JGraphT (graph algorithms), jHeaps (priority heaps)
- LLM service (e.g., OpenAI GPT-4)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Phase 1: Program Analysis
    subgraph "Phase 1: Program Analysis"
        subgraph "Ghidra Host"
            GHIDE_HEADLESS["TypeForge.java"]:::java
            GHIDE_GT["GroundTruth.java"]:::java
            EXT_PROP["extension.properties"]:::data
        end
        subgraph "Java Extension"
            subgraph Analyzer
                GEN["Generator.java"]:::java
                RET["ReTyper.java"]:::java
                TA["TypeAnalyzer.java"]:::java
            end
            subgraph Base
                AP[(AccessPoints.java)]:::java
                CG[(ConflictGraph.java)]:::java
                TFG[(TypeFlowGraph.java)]:::java
                CGR[(CallGraph.java)]:::java
                SDG[(SDGraph.java)]:::java
                FN[(FunctionNode.java)]:::java
                DTN[(DataTypeNode.java)]:::java
                PFNC[(PrepareFunctionNodeCallback.java)]:::java
                SWP[(SlidingWindowProcessor.java)]:::java
            end
            subgraph Utils
                DH["DecompilerHelper.java"]:::java
                LOG["Logging.java"]:::java
                DTH["DataTypeHelper.java"]:::java
            end
        end
        DATA[(data/)]:::data
        LIB[(lib/)]:::data
        JSON[(analysis_output.json)]:::data
    end

    %% Phase 2: LLM-Assisted Refinement
    subgraph "Phase 2: LLM-Assisted Refinement"
        TI["TypeInference.py"]:::python
        GTX["GroundTruthExtractor.py"]:::python
        DE["double_elimination.py"]:::python
        CFG[(config.yml)]:::data
        LLM(("LLM API")):::external
    end

    DEMO[(demo/)]:::output
    BINARY(("Stripped Binary")):::external

    %% Connections
    BINARY -->|input| TI
    TI -->|invoke headless| GHIDE_HEADLESS
    GHIDE_HEADLESS -->|loads| EXT_PROP
    GHIDE_HEADLESS -->|loads| DATA
    GHIDE_HEADLESS -->|loads| LIB
    GHIDE_HEADLESS -->|executes| GEN
    GEN --> RET
    RET --> TA
    TA -->|uses base & utils| AP
    AP --> CG
    CG --> TFG
    TFG --> CGR
    CGR --> SDG
    SDG --> FN
    FN --> DTN
    DTN --> PFNC
    PFNC --> SWP
    SWP -->|utilizes| DH
    DH --> LOG
    LOG --> DTH
    DTH -->|analysis complete| JSON

    JSON -->|consumed by| DE
    DE -->|calls| LLM
    LLM -->|response| DE
    DE -->|outputs refined JSON| DEMO

    %% Ground truth path
    BINARY -->|debug binary| GTX
    GTX -->|invoke headless| GHIDE_GT
    GHIDE_GT -->|loads| EXT_PROP
    GHIDE_GT -->|outputs| JSON

    %% Click Events
    click GHIDE_HEADLESS "https://github.com/noobone123/typeforge/blob/main/ghidra_scripts/TypeForge.java"
    click GHIDE_GT "https://github.com/noobone123/typeforge/blob/main/ghidra_scripts/GroundTruth.java"
    click EXT_PROP "https://github.com/noobone123/typeforge/blob/main/extension.properties"
    click GEN "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/analyzer/Generator.java"
    click RET "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/analyzer/ReTyper.java"
    click TA "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/analyzer/TypeAnalyzer.java"
    click AP "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/dataflow/AccessPoints.java"
    click CG "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/dataflow/ConflictGraph.java"
    click TFG "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/dataflow/TFG/TypeFlowGraph.java"
    click CGR "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/graph/CallGraph.java"
    click SDG "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/graph/SDGraph.java"
    click FN "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/node/FunctionNode.java"
    click DTN "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/node/DataTypeNode.java"
    click PFNC "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/parallel/PrepareFunctionNodeCallback.java"
    click SWP "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/base/passes/SlidingWindowProcessor.java"
    click DH "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/utils/DecompilerHelper.java"
    click LOG "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/utils/Logging.java"
    click DTH "https://github.com/noobone123/typeforge/blob/main/src/main/java/typeforge/utils/DataTypeHelper.java"
    click DATA "https://github.com/noobone123/typeforge/tree/main/data/"
    click LIB "https://github.com/noobone123/typeforge/tree/main/lib/"
    click TI "https://github.com/noobone123/typeforge/blob/main/scripts/TypeInference.py"
    click GTX "https://github.com/noobone123/typeforge/blob/main/scripts/GroundTruthExtractor.py"
    click DE "https://github.com/noobone123/typeforge/blob/main/scripts/judge/double_elimination.py"
    click CFG "https://github.com/noobone123/typeforge/blob/main/scripts/config.yml"
    click DEMO "https://github.com/noobone123/typeforge/tree/main/demo/"

    %% Styles
    classDef java fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef python fill:#90EE90,stroke:#000,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef output fill:#D3D3D3,stroke:#000,stroke-width:1px
```
