GitNexus Wiki Generator Architecture Documentation Approach

The GitNexus wiki generator implements a four-phase, LLM-driven pipeline that transforms repository knowledge graphs into modular Markdown documentation with automated Mermaid architecture diagrams.

The GitNexus wiki generator creates architecture documentation by analyzing your codebase's structure and dependencies. Unlike static documentation tools, it leverages a knowledge graph built in KuzuDB and large language models to produce developer-centric wiki pages that evolve with your code. This approach ensures that architecture diagrams and module descriptions remain grounded in actual source code relationships.

The Four-Phase Documentation Pipeline

The core logic resides in gitnexus/src/core/wiki/generator.ts, where the WikiGenerator.run method orchestrates the entire workflow. The pipeline processes your repository through distinct phases, each with specific responsibilities for building comprehensive architecture documentation.

Phase 0: Pre-flight Validation

Before generation begins, the system validates the repository state and loads the knowledge graph from KuzuDB. The WikiGenerator.run method determines whether to execute a full generation, an incremental update, or skip processing entirely if the documentation is already current. This decision logic ensures efficient resource usage by avoiding unnecessary LLM calls when the codebase hasn't changed meaningfully.

Phase 1: LLM-Driven Module Grouping

The generator sends a group-by-function prompt defined in GROUPING_SYSTEM_PROMPT (located in gitnexus/src/core/wiki/prompts.ts) to the LLM. This prompt instructs the model to assign every source file to a logical module—such as Authentication or Database—based on functional relationships rather than directory structure.

The LLM must return a strict JSON map. The generator validates this mapping and implements a fallback mechanism: if the response is malformed, it automatically reverts to directory-based grouping. This ensures robustness while preferring semantic organization when available.

Phase 2: Leaf Module Documentation

For each leaf module, the generator collects source code, intra-module call edges, and execution-flow traces from the knowledge graph via gitnexus/src/core/wiki/graph-queries.ts. It then invokes the LLM with MODULE_SYSTEM_PROMPT to write a developer-centric module document.

This prompt enforces strict requirements:

• Reference real symbols from the source code
• Optionally include a small Mermaid diagram for complex flows
• Stay within the configured maxTokensPerModule budget

Before calling the LLM, the generator estimates token counts using estimateTokens and truncates source code or splits large modules to remain within the LLM's context window.

Phase 3: Parent Module Summaries

When a module contains child modules, the generator synthesizes a summary page from the children's content using PARENT_SYSTEM_PROMPT. The LLM is explicitly instructed to reference only child modules (not individual source files), maintain concise descriptions, and include diagrams only when they genuinely clarify relationships between subsystems.

Phase 4: Overview Page with Architecture Diagrams

Finally, the generator constructs the top-level overview page via OVERVIEW_SYSTEM_PROMPT. This page serves as the entry point for new developers, listing module summaries and embedding a high-level Mermaid architecture diagram.

The prompt enforces strict constraints for this diagram:

• Maximum 10 nodes to ensure readability
• Use only inter-module call edges and key processes for accuracy
• Maintain brevity in explanatory text

After Markdown generation completes, gitnexus/src/core/wiki/html-viewer.ts bundles all pages into a static index.html file via generateHTMLViewer for easy browsing without a local server.

Key Architectural Features

Graph-First Documentation Approach

All documentation derives from a KuzuDB knowledge graph that stores files, symbols, call edges, and process traces. The generator queries this graph through graph-queries.ts to provide the LLM with concrete, source-grounded data rather than relying on file contents alone. This ensures that architecture diagrams reflect actual runtime relationships and dependencies.

Token Budget Management

The system implements token-aware processing through the estimateTokens function. Before each LLM invocation, the generator calculates the prompt size and automatically truncates source code or splits large modules to stay within the maxTokensPerModule limit. This prevents context window overflow while maximizing the amount of relevant code provided to the model.

Parallel Processing with Backoff

Leaf modules are processed in parallel using runParallel (lines 448-498 in generator.ts), which implements a configurable concurrency limit. When the LLM API returns HTTP 429 (rate limit) responses, the system automatically reduces concurrency and re-queues tasks. This optimizes throughput while respecting API rate limits.

Incremental Update Capability

The generator supports incremental documentation updates through the incrementalUpdate method (lines 891-1000). By storing the commit hash and a module-file mapping in meta.json, the system can identify which modules changed in a Git diff and regenerate only those pages. This dramatically reduces processing time for large repositories with small changes.

Deterministic Prompt Engineering

Every LLM interaction uses strict system prompts defined in prompts.ts with explicit rules: no invented APIs, no markdown formatting in JSON responses, limited diagram sizes, and mandatory symbol references. This deterministic approach ensures consistent output quality across different runs and models.

Resumable Snapshots

The generator creates a snapshot of the initial module tree in first_module_tree.json during the buildModuleTree process (lines 311-356). If the generation process crashes, it can resume from this snapshot without re-running the expensive LLM-based grouping phase, improving reliability for long-running documentation jobs.

Usage Examples

Command Line Generation

Generate architecture documentation for your repository using the CLI:

# Generate full wiki with architecture diagrams

npx gitnexus wiki --model gpt-4o-mini

This creates a wiki/ directory containing individual module pages, an overview.md with the high-level architecture diagram, and an index.html for browser-based navigation.

Programmatic Integration

Integrate the wiki generator into your Node.js applications:

import { WikiGenerator } from './gitnexus/src/core/wiki/generator.js';
import { resolveLLMConfig } from './gitnexus/src/core/wiki/llm-client.js';

// Configure LLM settings
const llmConfig = await resolveLLMConfig({ model: 'gpt-4o-mini' });

// Initialize generator with paths and options
const generator = new WikiGenerator(
  '/path/to/repository',
  '/path/to/.gitnexus/storage',
  '/usr/local/bin/kuzu',
  llmConfig,
  { 
    force: false, 
    maxTokensPerModule: 30000 
  },
  (phase, percentage, detail) => {
    console.log(`[${phase}] ${percentage}% – ${detail ?? ''}`);
  }
);

// Execute the four-phase pipeline
await generator.run();

Customizing Architecture Diagram Constraints

Modify the system prompts to adjust diagram complexity. For example, to reduce the overview diagram to 8 nodes instead of 10:

// In gitnexus/src/core/wiki/prompts.ts
export const OVERVIEW_SYSTEM_PROMPT = `You are a technical documentation writer.
Write the top-level overview page for a repository wiki.
...
- Include a high-level Mermaid architecture diagram showing **no more than 8 nodes**.`;

After editing, regenerate the documentation to apply the new constraints.

Summary

• GitNexus generates architecture documentation through a four-phase LLM pipeline that processes knowledge graph data into structured Markdown with Mermaid diagrams.
• The system uses deterministic prompts (GROUPING_SYSTEM_PROMPT, MODULE_SYSTEM_PROMPT, PARENT_SYSTEM_PROMPT, OVERVIEW_SYSTEM_PROMPT) to ensure consistent, source-grounded output.
• Token budget management and parallel processing with backoff optimize LLM usage while preventing rate limit errors.
• Incremental updates via incrementalUpdate and resumable snapshots via first_module_tree.json make the tool efficient for large, evolving repositories.
• The final output includes module-specific pages, a top-level overview with architecture diagrams, and a static HTML viewer for easy navigation.

Frequently Asked Questions

How does the GitNexus wiki generator create architecture diagrams?

The generator creates architecture diagrams by querying the KuzuDB knowledge graph for inter-module call edges and key processes, then instructing the LLM to generate Mermaid syntax through the OVERVIEW_SYSTEM_PROMPT. The prompt strictly limits diagrams to 10 nodes maximum for the overview page, ensuring high-level clarity while maintaining accuracy based on actual code relationships.

What happens if the LLM returns malformed JSON during module grouping?

If the LLM returns invalid JSON during the grouping phase (Phase 1), the generator implements a fallback mechanism that automatically reverts to directory-based grouping. This validation occurs immediately after the GROUPING_SYSTEM_PROMPT response is received, ensuring the pipeline continues robustly even when LLM outputs are unpredictable, while preferring semantic organization when available.

Can the GitNexus wiki generator update documentation incrementally?

Yes, the generator supports incremental updates through the incrementalUpdate method in generator.ts. By storing the commit hash and module-file mappings in meta.json, the system identifies which modules changed via Git diff and regenerates only affected pages. This approach dramatically reduces processing time for large repositories with small changes, making continuous documentation updates practical.

How does the generator manage LLM token limits when processing large modules?

The generator implements token budget awareness through the estimateTokens function, which calculates prompt size before each LLM invocation. If a module exceeds the maxTokensPerModule limit (default 30,000 tokens), the system automatically truncates source code or splits large modules into smaller chunks. This prevents context window overflow while maximizing the amount of relevant code provided to the LLM for accurate documentation generation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}