# GitNexus Wiki Generator Architecture Documentation Approach

> Discover the GitNexus wiki generator's four-phase LLM pipeline. Learn how it converts knowledge graphs into modular Markdown docs with automated Mermaid diagrams.

- Repository: [Abhigyan Patwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus)
- Tags: architecture
- Published: 2026-03-08

---

**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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/gitnexus/src/core/wiki/html-viewer.ts) bundles all pages into a static [`index.html`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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:

```bash

# 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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/overview.md) with the high-level architecture diagram, and an [`index.html`](https://github.com/abhigyanpatwari/GitNexus/blob/main/index.html) for browser-based navigation.

### Programmatic Integration

Integrate the wiki generator into your Node.js applications:

```ts
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:

```ts
// 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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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`](https://github.com/abhigyanpatwari/GitNexus/blob/main/generator.ts). By storing the commit hash and module-file mappings in [`meta.json`](https://github.com/abhigyanpatwari/GitNexus/blob/main/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.