src — docs

Module: src-docs Cohesion: 0.80 Members: 0

src — docs

The src/docs module is responsible for generating, managing, and providing access to comprehensive documentation for a codebase. It leverages a KnowledgeGraph to understand the project's structure, entities, and relationships, producing structured documentation that can be consumed by both human developers and AI agents.

This module encompasses several distinct phases: project discovery, blueprint generation, configuration, documentation rendering and export, and runtime context provision for AI agents.

Core Concepts

Before diving into the components, understanding the key data structures is crucial:

Key Components and Workflow

The src/docs module orchestrates a multi-stage process to generate and serve documentation. 

graph TD
    A[KnowledgeGraph] --> B(Project Discovery)
    B --> C{ProjectProfile}
    A --> D(Blueprint Builder)
    D --> E{ProjectBlueprint}

    subgraph Documentation Generation (V2 Pipeline - not shown)
        C & E --> F(LLM-driven Page Generation)
        F --> G(RenderInput Pages)
    end

    subgraph Documentation Generation (V1 - Deprecated)
        C & E --> H(docs-generator.ts)
        H --> G
    end

    G --> I(Doc Exporter)
    I --> J[Generated Docs <br/>(.codebuddy/docs/)]

    J --> K(Docs Context Provider)
    K --> L[Agent Runtime Context]

1. Configuration Management (src/docs/config.ts)

The config.ts module handles loading and managing documentation generation settings.

This configuration is loaded early in the documentation pipeline to guide subsequent generation steps.

2. Project Discovery (src/docs/discovery/project-discovery.ts)

The project-discovery.ts module performs an initial, LLM-agnostic analysis of the codebase to build a comprehensive ProjectProfile. This phase works on any codebase without project-specific assumptions.

The resulting ProjectProfile provides a rich, structured understanding of the codebase, which is then used by LLM-driven generation processes (in V2) or directly by the deprecated V1 generator.

3. Blueprint Generation (src/docs/blueprint-builder.ts)

The blueprint-builder.ts module creates a ProjectBlueprint from the KnowledgeGraph. This blueprint serves as a verified, factual representation of the codebase, primarily designed to provide ground truth to LLMs and prevent hallucinations.

The ProjectBlueprint is a critical component for LLM-based documentation, ensuring that the AI operates on accurate, pre-validated information about the codebase's structure and entities.

4. Documentation Generation (V1 - Deprecated) (src/docs/docs-generator.ts)

The docs-generator.ts module represents the deprecated V1 documentation generation approach. It directly generates a fixed set of markdown files based on hardcoded section logic. While deprecated in favor of the LLM-driven V2 pipeline (docs-pipeline.ts), its internal section generation functions provide insight into the types of content produced.

Note on Deprecation: While docs-generator.ts is provided, the comments and call graph indicate that src/docs/docs-pipeline.ts (V2) is the current recommended approach. The V2 pipeline likely uses the ProjectProfile and ProjectBlueprint to inform LLM calls (via src/docs/llm-docs-generator.ts) for more dynamic and intelligent content generation, rather than the fixed structure of V1.

5. Documentation Export (src/docs/doc-exporter.ts)

The doc-exporter.ts module is responsible for taking rendered documentation pages and writing them to disk in various formats.

This module acts as the final stage of the documentation pipeline, persisting the generated content.

6. Runtime Docs Context Provider (src/docs/docs-context-provider.ts)

The docs-context-provider.ts module makes the generated documentation available to AI agents at runtime. It acts as a searchable index for the documentation, allowing agents to retrieve relevant context based on user queries or to get an architectural overview.

This component is crucial for enabling AI agents to leverage the generated documentation effectively, providing them with up-to-date and relevant information about the codebase.

Integration with the Codebase

The src/docs module is deeply integrated with the src/knowledge module, particularly the KnowledgeGraph.

In summary, the src/docs module provides a robust framework for transforming a codebase's KnowledgeGraph into structured, searchable documentation, serving both human developers and AI agents.