How Litho's Documentation Generation Stage Composes Architectural Diagrams in deepwiki-rs

Litho composes architectural diagrams during its documentation generation stage by aggregating research data from multiple specialized agents, engineering detailed C4-model prompts, and invoking an LLM to generate Markdown documents embedded with Mermaid diagram syntax.

The sopaco/deepwiki-rs repository implements Litho, a documentation generator that transforms raw source code into structured architectural documentation. During the compose phase of Litho's documentation generation stage, the system orchestrates multiple AI agents to synthesize research findings into cohesive architectural diagrams following the C4 model.

The Architecture Composition Pipeline

Litho's compose phase operates through a coordinated pipeline that transforms raw research data into polished architectural documentation with embedded diagrams.

Research Data Collection

The composition process begins with the ArchitectureEditor agent retrieving structured research from the memory scope DOCUMENTATION / STUDIES_RESEARCH. This data originates from specialized research agents including SystemContextResearcher, DomainModulesDetector, ArchitectureResearcher, and WorkflowResearcher. The stored reports contain raw architectural data such as system context descriptions, domain-module relationships, and pre-generated Mermaid snippets (flowchart_mermaid, sequence_diagram_mermaid, etc.).

In src/generator/compose/agents/architecture_editor.rs (lines 29-33), the editor initializes by pulling these research materials from the memory scope to inform the diagram generation process.

Prompt Engineering for C4 Model Diagrams

The ArchitectureEditor implements the StepForwardAgent trait and defines a sophisticated prompt template that enforces C4 model compliance. The prompt_template() method constructs a system prompt that:

• Describes the required C4-model sections: System Context, Container, Component, Code, and Deployment (lines 59-66)
• Stipulates explicit diagram requirements: "Use Mermaid format to draw architecture diagrams; include system context diagrams, container diagrams, component diagrams; draw key business-process and technical-process diagrams" (lines 149-153)

This prompt engineering ensures the LLM generates standardized architectural visualization rather than unstructured text.

LLM Execution and Markdown Generation

The opening_instruction in src/generator/compose/agents/architecture_editor.rs (lines 77-91) directs the LLM to "write a complete, in-depth, and detailed C4 architecture document… Include clear architecture diagrams and flowcharts". The prompt injects the collected research data via the {research_materials} placeholder.

The StepForwardAgent trait's execute() method (implemented in src/generator/step_forward_agent.rs) sends the composed prompt to the configured LLM (selecting between efficient or powerful models based on llm_call_mode). The LLM returns a Markdown document containing embedded Mermaid diagram blocks that the system stores as the final architecture documentation string.

Post-Processing and Diagram Validation

After the compose agents generate the initial documentation, Litho applies automated validation to ensure diagram correctness.

The MermaidFixer Tool

The MermaidFixer in src/generator/outlet/fixer.rs executes the external mermaid-fixer tool via the auto_fix_after_output() method (lines 12-24, 48-57). This post-processing step:

• Scans the output directory for generated Mermaid diagrams
• Automatically detects syntax errors in the diagram blocks
• Repairs invalid Mermaid syntax to ensure renderability in standard Markdown viewers

This validation layer guarantees that the architectural diagrams produced during the compose phase are technically correct and visually renderable.

Orchestration of Compose Agents

The DocumentationComposer in src/generator/compose/mod.rs orchestrates the entire diagram composition workflow through its execute() method (lines 27-45). The system invokes agents in a fixed sequence:

1. OverviewEditor – Generates the System Context diagram
2. ArchitectureEditor – Produces Container and Component diagrams
3. WorkflowEditor – Documents business and technical processes
4. KeyModulesInsightEditor – Analyzes critical modules
5. BoundaryEditor – Defines system boundaries
6. DatabaseEditor (optional) – Documents database architecture

This orchestration ensures that architectural diagrams follow a logical progression from high-level context to detailed component views.

Code Examples

The following example demonstrates how the compose stage is invoked from the CLI entry point:

// src/main.rs (simplified)
let context = GeneratorContext::new(&config)?;
let mut doc_tree = DocTree::new();
let composer = DocumentationComposer::default();

composer.execute(&context, &mut doc_tree).await?;   // ← runs Overview, Architecture, Workflow, etc.
MermaidFixer::auto_fix_after_output(&context).await?; // ← fixes diagrams

To execute only the architecture diagram generation independently:

let arch_editor = ArchitectureEditor::default();
arch_editor.execute(&context).await?;

Key Source Files

File	Role
src/generator/compose/mod.rs	Orchestrates the full composition pipeline (calls each editor in order)
src/generator/compose/agents/architecture_editor.rs	Generates the C4 architecture sections and embeds Mermaid diagrams
src/generator/compose/agents/overview_editor.rs	Produces the System Context diagram
src/generator/outlet/fixer.rs	Runs the external mermaid-fixer tool
src/generator/step_forward_agent.rs	Base trait driving LLM calls for compose agents
src/generator/research/agents/architecture_researcher.rs	Supplies raw architecture data including Mermaid snippets

Summary

• Litho's documentation generation stage composes architectural diagrams through a multi-agent pipeline defined in src/generator/compose/mod.rs.
• The ArchitectureEditor agent aggregates research from SystemContextResearcher, DomainModulesDetector, and other research agents stored in the DOCUMENTATION memory scope.
• Prompt engineering enforces C4 model compliance and explicit Mermaid diagram requirements through the prompt_template() method.
• Post-processing via MermaidFixer ensures syntactic validity of generated diagrams before final output.

Frequently Asked Questions

What is the C4 model referenced in Litho's architecture documentation?

The C4 model is a framework for visualizing software architecture through four levels: System Context, Container, Component, and Code. Litho's ArchitectureEditor explicitly structures its prompts to generate documentation covering these four layers plus Deployment diagrams, ensuring standardized architectural visualization that follows industry best practices.

How does Litho ensure generated Mermaid diagrams are syntactically correct?

After the compose phase completes, the MermaidFixer in src/generator/outlet/fixer.rs executes the external mermaid-fixer tool via auto_fix_after_output(). This tool automatically detects and repairs syntax errors in the generated Mermaid diagram blocks, ensuring they render correctly in standard Markdown viewers without manual intervention.

Can I run the architecture diagram generation independently of other documentation sections?

Yes. While the standard pipeline orchestrates multiple agents through DocumentationComposer::execute(), you can instantiate and run the ArchitectureEditor directly. Import ArchitectureEditor from src/generator/compose/agents/architecture_editor.rs and call execute() with a valid GeneratorContext to generate only the C4 architecture sections and associated diagrams.

What research data sources feed into the architecture diagram composition?

The ArchitectureEditor consumes research reports stored in the DOCUMENTATION memory scope under STUDIES_RESEARCH. These reports originate from specialized agents including SystemContextResearcher, DomainModulesDetector, ArchitectureResearcher, and WorkflowResearcher, providing raw data such as system context descriptions, domain-module relationships, and pre-generated Mermaid snippets that inform the final diagram generation.

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