Skip to content

Project Overview

1. Foundation & Architecture

1.1 Project Overview: The Deterministic Knowledge Graph

GitGalaxy is, fundamentally, a high-velocity, deterministic function-level knowledge graph engine designed for very large codebases.

While the project is widely recognized for its interactive 3D WebGL visualizer—which renders repositories as explorable galaxies—this visualizer is ultimately just a presentation layer. The true core of the project is the analysis engine that powers next-generation Retrieval-Augmented Generation (RAG) pipelines.

We built GitGalaxy because modern software engineering has outgrown traditional analysis tools. Abstract Syntax Trees (ASTs) are computationally expensive, deeply fragile, and require fully compilable code—meaning they fail completely when analyzing legacy mainframes, incomplete snippets, or fragmented microservices. On the other end of the spectrum, Large Language Models (LLMs) suffer from severe context window limitations and output probabilistic, hallucination-prone architectural summaries.

GitGalaxy bridges this gap by generating a deterministic graph. Instead of asking an LLM to guess how code connects, GitGalaxy reads it from the source, the same way every time. It creates a structured, function-level map of the repository that serves as a repeatable retrieval foundation for RAG engines, allowing AI agents to surgically inject exact context rather than guessing across thousands of files.

1.2 The blAST Paradigm: Bypassing LLMs & ASTs

To achieve this, GitGalaxy abandons the AST entirely in favor of a novel algorithmic approach: blAST (Bypassing LLMs and ASTs).

The blAST engine works by treating code files as raw structural text, applying high-performance syntactic heuristics (regex) to scan for architectural triggers and functional anchors. It identifies exactly where a function starts (func_start), where a class is declared (class_start), how many parameters it couples with (args), and what state it mutates (flux).

By mapping these structural "physics," blAST builds a deterministic, function-level knowledge graph in seconds—without ever needing to compile or execute the code. It seamlessly handles mid-file language switching, assesses the architectural ratio of test files to logic, and extracts invaluable project structure data that standard parsers ignore.

When integrated into an AI pipeline as a RAG engine, GitGalaxy provides the LLM with a pre-computed map of reality. The LLM can retrieve the exact line numbers, structural mass, and dependency edges of a function, bypassing context limits and reducing architectural guesswork. The map has measured limits (for example, about half or more of calls are left unlinked where call resolution is measured); see Accuracy, measured.

The engine hunts for the universal structural markers of logic across the 78 languages and 367 file extensions in the language registry (as of 2026-11-04). The blAST engine scans source code for regular expression (regex) profiles that indicate specific architectural intent. It parses the software's heuristics to identify: * Structural Purity: Where does the actual logic live versus the literature and comments? * Network Topology: How do files mechanically couple to one another? * Behavioral Traits: Does this file act as a pure data producer, an orchestrator, or a UI view?

Hyper-Scale Velocity By bypassing the compiler bottleneck and focusing on lexical alignment, blAST achieves processing velocities that traditional scanners cannot match: * Small and fast: Apollo 11's guidance computer source (262 tracked files, 131,923 lines processed) in 1.28 s of engine time, single run of 2026-11-08 at engine 3bb225071 (the teardown). * Large Scale: Kubernetes, 2.46M analyzed lines, took about 65 s in a single run (2026-09-19, v2.9.1); a handful of 20M+ LOC outliers take minutes. See Every size, in seconds. * The OpenCV figure an earlier version of this page quoted (3.2M lines in 11.11 s) is from an older engine and is not re-measured here.

1.3 The Hub and Spoke Architecture

Because the blAST engine creates a perfectly standardized, queryable dataset (outputting to SQLite and highly optimized JSON), it acts as a central "Hub." The raw telemetry generated by the engine powers a massive ecosystem of specialized "Spokes" designed for enterprise engineering operations:

  • Legacy Modernization: Automated pipelines that utilize the engine's graphs to map, slice, and refactor legacy COBOL monoliths into modern Java Spring Boot microservices.
  • Supply Chain Security: Zero-trust firewalls that verify the physical reality of dependencies against Unicode homoglyphs and malicious execution headers.
  • Boundary Cartography: Full API network maps that compare physical codebase routers against official Swagger documentation to hunt down "Shadow APIs."
  • Compliance & Auditing: High-speed log parsers and SBOM generators that run on the engine's foundational logic to track PII leaks and verify software bills of materials.

1.4 Visualizing Complexity: The Artistic Layer

Code can be art. Logic can be art. Systems engineering can be art.

While the engine outputs forensic databases, humans are not optimized for processing rows of digits in a SQLite table; we are optimized for detecting patterns in nature and physics. The GitGalaxy Visualizer translates the engine's raw telemetry into a generative 3D environment.

GitGalaxy maps the calculated complexity to spatial position, movement, pulses, and colors, tapping into our evolutionary strengths to help us understand complex systems intuitively. It renders codebases with the following visual metaphors:

  • Files = Stars orbiting around an unseen black hole.
  • File Relationships (Dependencies) = Relative spatial locations of stars in the galaxy.
  • Inbound Imports (Gravity) = A star's pulse rate.
  • Functions / Classes = Satellites orbiting the stars.
  • Function Complexity = Arrangement, number, and size of satellites in a unit.
  • Languages Used = Base color overlays.

1.5 System File Map: Hub & Spoke Architecture

The backend ecosystem is organized into strict domains, separating the core graphing logic from the operational toolsets:

gitgalaxy/
├── galaxyscope.py                  # The Main CLI Entry Point
├── core/                           # The Hub: File ingestion, network graphing, and lens routing
├── physics/                        # The Engine: Signal processing, ML analytics, and chronometers
├── recorders/                      # The Exporters: JSON, SQLite, and LLM-ready markdown generators
├── security/                       # The Threat Layer: XGBoost inference, SAST lens, and AI guardrails
├── standards/                      # The Universal Laws: Language heuristics and analysis schemas
└── tools/                          # The Spokes: Enterprise operations driven by the core graph
    ├── cobol_to_cobol/             # Legacy modernization and JCL analysis
    ├── cobol_to_java/              # Automated Spring Boot microservice forging
    ├── compliance/                 # Zero-Trust SBOM generators
    ├── network_auditing/           # API boundary mappers (Shadow API hunting)
    ├── supply_chain_security/      # Quarantines, vault sentinels, and binary X-Rays
    └── terabyte_log_scanning/      # High-velocity PII leak and mainframe SMF telemetry hunters

1.6 Measuring Structural Surface, Not "Code Quality"

GitGalaxy assesses deviations from organizational standards and displays that info as localized heatmaps onto the 3D generated world. Importantly, GitGalaxy does not measure subjective "Code Quality." It measures a Structural Surface Profile: where a structural or content pattern is concentrated relative to the rest of the repository. It describes; it does not predict defects (what it claims, docs/vectors.md). Our measurements do not judge; they highlight. They function as sensors, not critics.

  • We do not assess "Bad Code"; we measure Cognitive Load Exposure—how hard it is for a human to work through the logic.
  • We do not assess "Missing Docs"; we assess Documentation Exposure—how much of the logic carries no explanation, which matters if a key person leaves.
  • We do not measure "System Security"; we measure Safety Exposure—where try/except blocks and error handling are sparse relative to the rest of the repo.

By visualizing these exposures as toggleable color overlays, the visualizer provides an intuitive non-numeric dashboard. It allows an architecture team to agree on standards and instantly see—without reading a single line of text—where their system is drifting from those standards.

1.7 Zero-Trust Privacy Protocol

Whether you are running the command-line engine or the WebGL visualizer, GitGalaxy operates on a strict Zero-Trust Privacy Model: Your code never leaves your computer.

  • No Data Transmission: Source code is never transmitted to any API, cloud database, or third-party LLM service.
  • Air-Gap Ready: The entire suite of tools is designed to run in highly secure, internet-disconnected environments.
  • Ephemeral Memory Processing: Repositories are unpacked into a volatile memory buffer and are automatically purged when the operation completes.



🌌 Powered by the blAST Engine

This documentation is part of the GitGalaxy Ecosystem, an AST-free, LLM-free heuristic knowledge graph engine.

⬅️ Back to Master Index