Binary Reconstruction Graph

Binary Reconstruction Graph is a local-first workbench for reconstructing binary asset, model, and render pipelines from reverse-engineering evidence. It is built for graphing how executable functions transform raw data into parseable structures and hardware-facing output, with a current focus on PlayStation 1 model/render pipelines imported from Ghidra.

The project is evidence-first and conservative by design. It does not try to turn decompiled code into confident claims by vibes. It stores functions, data objects, regions, tables, streams, hardware anchors, typed edges, evidence snippets, review artifacts, and accepted reconstruction facts so you can gradually turn a messy reverse-engineering session into a codegen-ready map.

What It Does

• Imports Ghidra functions, neighborhoods, and function pointer tables.
• Builds a workflow-scoped reconstruction graph with typed function/data/hardware relationships.
• Models data objects such as compressed blobs, model blobs, object tables, vertex pools, normal pools, primitive streams, texture blobs, GP0 packet buffers, and ordering tables.
• Detects and inspects dispatch tables, including primitive render handler tables.
• Analyzes primitive handlers for RTPT/NCCS/DPCT/GP0/OT usage and primitive-format clues.
• Stores review-first LLM structural inference artifacts without auto-applying them.
• Lets you accept confirmed layout facts as first-class reconstruction facts.
• Exports compact graph JSON, full graph JSON, reconstruction bundles, data layout JSON, and viewer/parser prompts.
• Scores viewer readiness conservatively so missing layouts are visible instead of hand-waved.

What It Is Not

• Not a game model parser yet.
• Not a replacement for Ghidra.
• Not centered on semantic tagging.
• Not an auto-decompiler-to-viewer magic button.

The intended loop is: import evidence, inspect the graph, propose structural facts, review them, accept only what is supported, export a reconstruction bundle, then build/debug parsers from that bundle.

Current Focus

The active reference workflow is the combined Model Viewer Pipeline:

compressed_blob
  -> decompressed_model_blob
  -> model_blob
  -> object_table / vertex_pool / normal_pool / primitive_stream / texture_blob
  -> primitive render dispatch table
  -> render handler functions
  -> RTPT / NCCS / DPCT
  -> GP0_packet_buffer
  -> OrderingTable
  -> GP0 / DMA_GPU

The app is especially useful for mapping PS1 primitive streams, handler dispatch tables, packed vertex/normal offsets, GP0 packet emission, and ordering-table insertion paths.

Architecture

• Desktop shell: Tauri v2
• Frontend: React, TypeScript, Vite
• Graph UI: React Flow via @xyflow/react
• Persistence: SQLite
• Backend: local Python HTTP service
• Optional integration: ghidra_bridge
• Optional LLM provider: OpenAI-compatible API
• Primary target platform: Windows

Repository Layout

backend/python/                 Local backend service and SQLite persistence
backend/python/analysis/        Structural inference, coverage, and review helpers
backend/python/exports/         Reconstruction bundle and pipeline JSON exporters
backend/python/inference/       Deterministic graph/dataflow inference
backend/python/integrations/    Ghidra bridge client and address normalization
backend/python/providers/       OpenAI-compatible provider layer
backend/python/seed/            Built-in demo and workflow seed data
frontend/src/                   React application
src-tauri/                      Tauri desktop shell
shared/                         Shared contracts and notes
tests/                          Backend/unit regression tests

Public Repo Safety

This project is designed to keep reverse-engineering data local. The default .gitignore excludes:

• .localdata/
• SQLite database files
• .env files
• build output
• dependency folders
• Python and TypeScript caches

Before publishing your own fork, double-check that you are not committing proprietary binaries, game assets, private decompile text, API keys, local database files, or screenshots containing sensitive material.

Prerequisites

• Node.js 20+
• Python 3.11+
• Rust and Cargo for Tauri desktop builds
• Microsoft Visual Studio C++ Build Tools for Tauri on Windows
• WebView2 runtime on Windows
• Optional: Ghidra with ghidra_bridge

Setup

npm install
pip install -r backend\python\requirements.txt
Copy-Item .env.example .env

Optional local data directory:

$env:BINARY_RECONSTRUCTION_GRAPH_DATA_DIR=".localdata"

The legacy SEMANTIC_MAPPER_DATA_DIR environment variable is still honored for existing local installs.

Run Locally

Start the backend:

python -m backend.python.main seed
python -m backend.python.main serve

Start the frontend:

npm run dev

Run the desktop shell:

npm run tauri:dev

Build the frontend:

npm run build

Run tests:

python -m unittest discover tests

Ghidra Integration

Ghidra support is optional. When connected, the app can import:

• current function
• current function neighborhood
• arbitrary function address
• all functions already visible in the graph
• manual function pointer tables / dispatch tables

Function pointer table import is important for render pipelines because indirect dispatch targets are often invisible to plain caller/callee expansion.

Example table workflow:

start address: 0x8007659c
entry count:   20
name:          primitive_render_handler_table

The workbench creates a dispatch table node, function nodes for targets, dispatches_to edges, and a primitive_stream -> dispatch table selector relationship when supported.

LLM Structural Inference

LLM use is optional and review-first.

The app can ask an OpenAI-compatible provider to infer structural facts from selected decompiled functions, such as:

• primitive stream stride
• primitive command fields
• vertex/normal pool stride
• packed offset fields
• triangle assembly
• GP0 packet word count
• OT insertion
• handler feature evidence

The LLM does not auto-apply facts. Results are stored as review artifacts. You can accept, reject, edit, clear, or export them. Accepted facts are persisted as reconstruction_facts with source and evidence metadata.

Exports

The app exposes several export paths:

• Compact Graph JSON for sharing with ChatGPT or another assistant.
• Full Graph JSON for complete local state.
• Data Layout JSON for parseable regions, fields, strides, and unknowns.
• Reconstruction Bundle JSON for Codex/parser/viewer work.
• Primitive Format Map for dispatch-table-driven render handlers.
• Viewer scaffold prompt and parser/debugging prompt generation.
• High-resolution graph screenshot export.

Compact exports intentionally omit large decompile text and focus on graph shape, normalized edges, evidence summaries, dominant paths, accepted facts, data layout, unresolved gaps, and primitive-format hints.

Development Notes

Useful commands:

npm run build
python -m unittest tests.test_reconstruction_workbench
python -m unittest discover tests
python -m backend.python.main serve

The app keeps old semantic-tagging tables for compatibility with earlier local data, but the core workflow is dataflow reconstruction.

Status

This is an active reverse-engineering workbench, not a polished consumer tool. Expect rough edges around Ghidra connectivity, LLM provider behavior, and project-specific inference heuristics. The strongest parts today are graph persistence, typed dataflow modeling, dispatch table import, primitive handler analysis, review-first layout inference, and reconstruction exports.

License

No license has been selected yet. Until a license is added, the code is public source but not explicitly open source. Choose a license before inviting outside reuse or contributions.