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

> Discover how Litho composes architectural diagrams in deepwiki-rs. Learn to aggregate data, engineer C4 model prompts, and use LLMs for Mermaid diagram generation.

- Repository: [Sopaco/deepwiki-rs](https://github.com/sopaco/deepwiki-rs)
- Tags: architecture
- Published: 2026-02-16

---

**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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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:

```rust
// 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:

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

```

## Key Source Files

| File | Role |
|------|------|
| [`src/generator/compose/mod.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/mod.rs) | Orchestrates the full composition pipeline (calls each editor in order) |
| [`src/generator/compose/agents/architecture_editor.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/agents/architecture_editor.rs) | Generates the C4 architecture sections and embeds Mermaid diagrams |
| [`src/generator/compose/agents/overview_editor.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/agents/overview_editor.rs) | Produces the System Context diagram |
| [`src/generator/outlet/fixer.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/outlet/fixer.rs) | Runs the external `mermaid-fixer` tool |
| [`src/generator/step_forward_agent.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/step_forward_agent.rs) | Base trait driving LLM calls for compose agents |
| [`src/generator/research/agents/architecture_researcher.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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`](https://github.com/sopaco/deepwiki-rs/blob/main/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.