GitNexus Architecture

Auto-generated from the GitNexus knowledge graph (1021 symbols, 2552 edges, 79 execution flows).

Overview

GitNexus is a graph-powered code intelligence platform that indexes codebases into a knowledge graph and exposes them via MCP (Model Context Protocol) tools for AI agents. It consists of three packages:

gitnexus/ — Core CLI + MCP server (published to npm). Indexes repositories, stores graphs in KuzuDB, and serves queries.
gitnexus-web/ — Browser-based frontend with WebAssembly tree-sitter and in-browser KuzuDB.
gitnexus-claude-plugin/ / gitnexus-cursor-integration/ — IDE integrations that augment AI agent tool calls with graph context.

Functional Areas

The codebase is organized into 14 functional clusters detected by community analysis:

Module	Symbols	Cohesion	Responsibility
Ingestion	108	24%	Multi-phase pipeline: file walking, tree-sitter parsing, import resolution, call tracing, heritage extraction, community detection, process tracing
Kuzu	50	23%	KuzuDB graph storage adapter, CSV generation, schema management, query execution
Embeddings	46	35%	Embedding pipeline: text generation from symbols, ONNX model inference, vector storage
Components	41	35%	Web UI React components (graph visualization, search, navigation)
Local	38	15%	MCP backend: tool implementations (query, context, impact, rename), resource handlers, search (BM25 + semantic)
Workers	38	27%	Web Workers for browser-side ingestion and tree-sitter parsing; Node.js worker threads for parallel parsing
LLM	28	37%	LLM-based cluster enrichment, prompt building, provider abstraction
CLI	24	35%	Command handlers (analyze, setup, serve, mcp), AI context file generation, IDE hook/skill installation
Storage	22	32%	Repository registry, `.gitnexus/` directory management, staleness detection
Services	14	31%	Shared services (config, ignore patterns, language support)
Hooks	12	56%	Claude Code / Cursor hook scripts for augmenting search tools with graph context
Search	11	36%	Hybrid search: BM25 keyword index + semantic vector search with reciprocal rank fusion

Key Execution Flows

1. CLI Analyze Pipeline

The primary ingestion path when a user runs npx gitnexus analyze:

analyzeCommand (cli/analyze.ts)
  → runPipelineFromRepo (ingestion/pipeline.ts)
    → walkRepository          — concurrent file I/O (32 parallel reads)
    → processStructure        — folder/file graph nodes
    → processParsing          — tree-sitter AST parsing (worker threads)
    → processImports          — import/require/use resolution
    → processCalls            — function call tracing with confidence
    → processHeritage         — extends/implements relationships
    → processCommunities      — Leiden community detection
    → processProcesses        — execution flow tracing
  → loadGraphToKuzu           — CSV export → KuzuDB bulk import
  → runEmbeddingPipeline      — generate + store symbol embeddings
  → generateAIContextFiles    — write CLAUDE.md, AGENTS.md, skills

2. MCP Server Request Flow

When an AI agent calls a GitNexus MCP tool:

mcpCommand (cli/mcp.ts)
  → startMCPServer (mcp/server.ts)
    → callTool (mcp/local/local-backend.ts)
      → ensureInitialized     — lazy KuzuDB connection + embedder init
      → query/context/impact  — graph traversal via KuzuDB Cypher
      → semanticSearch        — ONNX embedding + vector similarity
    → readResource (mcp/resources.ts)
      → queryClusters/queryProcesses — direct graph queries

3. Graph Storage Pipeline

loadGraphToKuzu (kuzu/kuzu-adapter.ts)
  → generateAllCSVs (kuzu/csv-generator.ts)
    → generateFileCSV         — node CSVs per label type
    → escapeCSVField          — UTF-8 sanitization
  → KuzuDB COPY FROM          — bulk CSV import
  → createIndexes             — property indexes for query performance

4. Embedding Pipeline

runEmbeddingPipeline (embeddings/embedding-pipeline.ts)
  → generateBatchEmbeddingTexts (embeddings/text-generator.ts)
    → generateEmbeddingText   — symbol → natural language description
    → generateFunctionText    — include signature, calls, file context
    → cleanContent            — strip noise, truncate
  → embedBatch                — ONNX Runtime inference (all-MiniLM-L6-v2)
  → storeEmbeddings           — KuzuDB vector storage

5. Web App Pipeline (Browser)

AppStateProvider (hooks/useAppState.tsx)
  → runPipeline (workers/ingestion.worker.ts)   — Web Worker
    → runPipelineFromFiles (ingestion/pipeline.ts)
      → createKnowledgeGraph
      → processParsing        — WASM tree-sitter
      → processImports/Calls/Heritage
      → processCommunities/Processes
  → loadGraphToKuzu           — in-browser KuzuDB (WASM)

Architecture Diagram

graph TB
    subgraph CLI["CLI Layer"]
        analyze["analyze command"]
        setup["setup command"]
        mcp_cmd["mcp command"]
        serve["serve command"]
        augment["augment command"]
    end

    subgraph Ingestion["Ingestion Pipeline"]
        walker["Filesystem Walker<br/>(concurrent I/O)"]
        structure["Structure Processor"]
        parsing["Parsing Processor<br/>(worker threads)"]
        imports["Import Processor"]
        calls["Call Processor"]
        heritage["Heritage Processor"]
        communities["Community Detection<br/>(Leiden)"]
        processes["Process Tracing"]
    end

    subgraph TreeSitter["Tree-Sitter"]
        parser_loader["Parser Loader"]
        ts_queries["Language Queries<br/>(9 languages)"]
        worker_pool["Worker Pool"]
        parse_worker["Parse Workers"]
    end

    subgraph MCP["MCP Server"]
        server["MCP Server<br/>(stdio transport)"]
        tools["Tools: query, context,<br/>impact, rename, cypher"]
        resources["Resources: clusters,<br/>processes, schema"]
        backend["Local Backend"]
    end

    subgraph Storage["Storage Layer"]
        kuzu["KuzuDB<br/>(graph store)"]
        csv_gen["CSV Generator"]
        repo_mgr["Repo Manager<br/>(~/.gitnexus registry)"]
    end

    subgraph Search["Search Engine"]
        bm25["BM25 Keyword Index"]
        semantic["Semantic Search<br/>(all-MiniLM-L6-v2)"]
        embedder["ONNX Embedder"]
    end

    subgraph Hooks["IDE Integration"]
        claude_hook["Claude Code Hooks"]
        cursor_hook["Cursor Hooks"]
        skills["Skills<br/>(exploring, debugging,<br/>impact, refactoring)"]
    end

    subgraph Web["Web Frontend"]
        app["React App"]
        web_worker["Web Worker<br/>(WASM ingestion)"]
        components["Graph Visualization"]
    end

    %% CLI → Ingestion
    analyze --> walker
    walker --> structure --> parsing --> imports --> calls --> heritage --> communities --> processes

    %% Parsing uses tree-sitter workers
    parsing --> worker_pool --> parse_worker
    parse_worker --> parser_loader
    parse_worker --> ts_queries

    %% Ingestion → Storage
    processes --> csv_gen --> kuzu
    processes --> embedder

    %% MCP flow
    mcp_cmd --> server --> tools --> backend --> kuzu
    server --> resources --> backend
    backend --> bm25
    backend --> semantic --> embedder

    %% CLI → Setup
    setup --> repo_mgr
    setup --> claude_hook
    setup --> cursor_hook
    setup --> skills

    %% Hooks → MCP
    claude_hook -.->|augments searches| tools
    cursor_hook -.->|augments searches| tools
    augment -.->|fast CLI path| backend

    %% Web
    app --> web_worker --> components
    web_worker --> kuzu

    %% Serve
    serve --> backend

Data Flow Summary

Source Code
    │
    ▼
┌─────────────────────────────────────────┐
│  Ingestion Pipeline (8 phases)          │
│  Files → AST → Symbols → Relationships │
│  → Communities → Execution Flows        │
└─────────────────┬───────────────────────┘
                  │
          ┌───────┴───────┐
          ▼               ▼
    ┌──────────┐   ┌────────────┐
    │  KuzuDB  │   │ Embeddings │
    │  (graph) │   │ (vectors)  │
    └────┬─────┘   └─────┬──────┘
         │               │
         └───────┬───────┘
                 ▼
         ┌──────────────┐
         │  MCP Server  │
         │  (7 tools)   │
         └──────┬───────┘
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
 Claude      Cursor      Other
  Code      Editor     MCP Clients

Supported Languages

Tree-sitter grammars are included for: TypeScript, JavaScript, Python, Java, C, C++, C#, Go, Rust.

Key Design Decisions

Augmentation over replacement — Hooks enrich existing AI agent tools (Grep, Glob, Bash) with graph context rather than replacing them
Native tree-sitter — Uses N-API bindings (not WASM) in the CLI for performance; WASM in the browser
Worker thread parsing — CPU-bound tree-sitter parsing parallelized across cpus - 1 worker threads
Hybrid search — BM25 keyword + semantic vector search combined with Reciprocal Rank Fusion for ranking
LRU AST cache — Parsed trees are cached across pipeline phases to avoid redundant re-parsing
Deterministic IDs — generateId(label, qualifiedName) ensures idempotent graph construction

9.9 KiB Raw Blame History