GitNexus/ARCHITECTURE.md

Architecture — GitNexus

This repository is a monorepo with two main products: the CLI / MCP package (gitnexus/) and the browser UI (gitnexus-web/). Supporting folders ship editor integrations and plugins without changing the core graph engine.

Repository layout

Path	Role
gitnexus/	Published npm package gitnexus: CLI, MCP server (stdio), local HTTP API for bridge mode, ingestion pipeline, LadybugDB graph, embeddings (optional).
gitnexus-web/	Vite + React UI: in-browser indexing (WASM), graph visualization, optional connection to gitnexus serve.
.claude/, gitnexus-claude-plugin/, gitnexus-cursor-integration/	Packaged skills and plugin metadata so agents discover the same workflows as documented in AGENTS.md.
eval/	Evaluation harnesses and docs for benchmarking tool usage.
.github/	CI workflows (quality, unit, integration, E2E) and composite actions.

End-to-end flow: index → graph → tools

1. Ingestion (gitnexus analyze)

   • Entry: gitnexus/src/cli/analyze.ts → runPipelineFromRepo in gitnexus/src/core/ingestion/pipeline.ts.
   • The pipeline is structured as a DAG (Directed Acyclic Graph) of named phases (see Pipeline Phase DAG below).
   • Output is loaded into LadybugDB under .gitnexus/ at the repo root (lbug/, meta.json, etc.). Optional FTS indexes and embeddings attach to the same store.
   • The repo is registered in ~/.gitnexus/registry.json so MCP can find it from any working directory.

2. Persistence & metadata

   • gitnexus/src/storage/repo-manager.ts — paths, registry, cleanup of legacy Kuzu artifacts.
   • gitnexus/src/core/lbug/lbug-adapter.ts — graph load, queries, embedding restore batches.

3. Query & agents

   • MCP (stdio): gitnexus/src/cli/mcp.ts → startMCPServer → LocalBackend (gitnexus/src/mcp/local/local-backend.ts) opens registered repos and serves tools from gitnexus/src/mcp/tools.ts and resources from gitnexus/src/mcp/resources.ts.
   • Bridge HTTP: gitnexus/src/cli/serve.ts → Express app in gitnexus/src/server/api.ts (CORS-limited) exposes REST + MCP-over-HTTP for the web UI.
   • CLI tools (no MCP): gitnexus query, context, impact, cypher in gitnexus/src/cli/tool.ts call the same backend for scripts and CI.

4. Staleness

   • gitnexus/src/mcp/staleness.ts compares indexed lastCommit to HEAD and surfaces hints when the graph is behind git.

MCP tools (summary)

Tool	Purpose
list_repos	Discover indexed repositories when more than one is registered.
query	Natural-language / keyword search over the graph (hybrid BM25 + optional vectors).
cypher	Ad hoc Cypher against the schema (see resource gitnexus://repo/{name}/schema).
context	Callers, callees, processes for one symbol (with disambiguation).
impact	Blast radius (upstream/downstream) with depth and risk summary.
detect_changes	Map git diffs to affected symbols and processes.
rename	Graph-assisted rename with dry_run preview (graph vs text_search confidence).

Where to change what

If you are changing…	Start in…
CLI commands / flags	gitnexus/src/cli/ (index.ts, per-command modules).
Parsing or graph construction	gitnexus/src/core/ingestion/pipeline-phases/ (individual phase files), pipeline.ts (orchestrator).
Graph schema / DB access	gitnexus/src/core/lbug/ (schema.ts, lbug-adapter.ts), gitnexus/src/mcp/core/lbug-adapter.ts if MCP-specific.
MCP protocol, tools, resources	gitnexus/src/mcp/server.ts, tools.ts, resources.ts.
Search ranking	gitnexus/src/core/search/ (BM25, hybrid fusion).
Embeddings	gitnexus/src/core/embeddings/, phases in analyze.ts.
Wiki generation	gitnexus/src/core/wiki/.
Web UI behavior	gitnexus-web/src/ (components, workers, graph client).
CI	.github/workflows/*.yml, .github/actions/setup-gitnexus/.

Pipeline Phase DAG

The ingestion pipeline is a DAG of named phases. Each phase is defined in its own file under gitnexus/src/core/ingestion/pipeline-phases/ with explicit dependencies, typed inputs, and typed outputs.

scan → structure → [markdown, cobol] → parse → [routes, tools, orm]
  → crossFile → mro → communities → processes

Phase files

Phase	File	Dependencies	What it does
scan	scan.ts	(root)	Walk repo filesystem, collect paths + sizes
structure	structure.ts	scan	Build File/Folder nodes + CONTAINS edges
markdown	markdown.ts	structure	Extract headings and cross-links from .md/.mdx
cobol	cobol.ts	structure	Regex-based COBOL/JCL extraction
parse	parse.ts + parse-impl.ts	structure, markdown, cobol	Chunked tree-sitter parse, import/call/heritage resolution
routes	routes.ts	parse	Route registry (Next.js, Expo, PHP, decorator-based)
tools	tools.ts	parse	MCP/RPC tool detection
orm	orm.ts	parse	Prisma/Supabase ORM query edges
crossFile	cross-file.ts + cross-file-impl.ts	parse, routes, tools, orm	Cross-file type propagation in topological order
mro	mro.ts	crossFile	Method Resolution Order, METHOD_OVERRIDES edges
communities	communities.ts	mro	Leiden community detection
processes	processes.ts	communities, routes, tools	Execution flow detection, Route/Tool → Process links

How to add a new phase

1. Create a new file in pipeline-phases/ (e.g. my-phase.ts)
2. Define a PipelinePhase<MyOutput> object with name, deps, and execute(ctx, deps)
3. Export it from pipeline-phases/index.ts
4. Add it to the buildPhaseList() function in pipeline.ts

// pipeline-phases/my-phase.ts
import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
import { getPhaseOutput } from './types.js';
import type { ParseOutput } from './parse.js';

export interface MyPhaseOutput { /* ... */ }

export const myPhase: PipelinePhase<MyPhaseOutput> = {
  name: 'myPhase',
  deps: ['parse'],   // runs after parse completes
  async execute(ctx, deps) {
    const { allPaths } = getPhaseOutput<ParseOutput>(deps, 'parse');
    // ... do work, write to ctx.graph ...
    return { /* typed output */ };
  },
};

DAG runner

The runner (pipeline-phases/runner.ts) validates the DAG at startup (detects cycles and missing deps via topological sort), then executes phases in dependency order. Each phase receives:

• ctx: PipelineContext — shared graph, repoPath, progress callback
• deps: Map<string, PhaseResult> — outputs from all upstream phases

Known limitations

Overloaded method resolution

Method and Constructor node IDs include an arity suffix (#<paramCount>) to disambiguate overloaded methods. Two overloads with different parameter counts produce distinct graph nodes: Method:file:Class.method#1 vs Method:file:Class.method#2.

Same-arity overload disambiguation: When two overloads share the same parameter count but differ in types (e.g. save(int) vs save(String)), a type-hash suffix ~type1,type2 is appended to produce distinct node IDs: Method:file:Class.save#1~int vs Method:file:Class.save#1~String. The suffix is only added when a same-arity collision is detected within a class and all parameters have non-null type annotations. Languages without type info (Python, Ruby, JS) fall back to arity-only IDs. TypeScript/JavaScript overload signatures are intentionally excluded from type-hashing because they are declaration-only contracts that should collapse to the implementation body's node ID. See issue #651.

C++ const-qualified overload disambiguation: Methods overloaded by const qualification (e.g. begin() vs begin() const) are disambiguated via an isConst property and a $const ID suffix appended to the const-qualified variant when a non-const collision exists. The $const suffix appears after the type-hash suffix: e.g. Method:file:Container.begin#0$const.

Generic/template type preservation in type-hash: The type-hash suffix uses rawType (full AST text including generic/template args) rather than the simplified type from extractSimpleTypeName. This means C++ template overloads like process(vector<int>) vs process(vector<string>) produce distinct IDs: ~vector<int> vs ~vector<std::string>. Java generic overloads like process(List<String>) vs process(List<Integer>) are a compile error due to type erasure, so this gap is theoretical for Java.

ID stability on first overload: Type and const tags are collision-only. When a class has save(int) as its only save method, the ID is save#1 (no tag). Adding save(String) changes the original to save#1~int. This is correct for fresh analysis but means IDs are not stable across overload additions. Future incremental re-analysis should account for this.

Variadic method matching: When one side is variadic (parameterCount undefined) and the other has a fixed count, METHOD_IMPLEMENTS edges are emitted with confidence 0.7 instead of 1.0. Variadic methods like foo(String... args) may superficially match foo(String s) by type but are not guaranteed to be interchangeable across all languages (Java/Kotlin accept this via varargs sugar; TypeScript, C#, Rust do not).

Confidence tiering for METHOD_IMPLEMENTS edges:

Match quality	Confidence	When
Exact parameter types match	1.0	Both sides have parameterTypes arrays and they match
Arity (count) matches	1.0	Both sides have parameterCount, types unavailable
Variadic vs fixed	0.7	One side is variadic, other has fixed count
Lenient (insufficient info)	0.7	One or both sides lack type and count data

Related docs

• MIGRATION.md — breaking changes and migration guidance.
• RUNBOOK.md — operational commands and recovery.
• GUARDRAILS.md — safety boundaries for humans and agents.
• TESTING.md — how to run tests.
• AGENTS.md / CLAUDE.md — agent workflows and tool usage expectations for this repo when indexed by GitNexus.