How Litho Generates C4 Model Documentation from Rust Code: A Complete Technical Guide

Litho automates C4 architecture documentation by parsing Rust source files, extracting code insights via regex-based analysis, and orchestrating LLM agents to generate System Context, Container, and Component diagrams in Markdown format.

Litho, the CLI tool defined in the sopaco/deepwiki-rs repository, implements a fully automated pipeline that transforms Rust codebases into professional C4 architecture documents. This article explains how Litho generates C4 model documentation from Rust code through a four-stage pipeline involving code extraction, research orchestration, and documentation composition.

The Four-Stage Pipeline

Litho processes Rust code through four distinct phases: CLI initialization, pre-processing and extraction, research orchestration, and documentation composition. Each stage is implemented as a modular component in the sopaco/deepwiki-rs codebase, with data flowing through a shared Memory system.

Stage 1: CLI Entry Point and Configuration

The pipeline begins in [src/cli.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/cli.rs), where the Args struct parses user inputs including --project-path, --output-path, and model selections. The Args::to_config() method transforms these arguments into a Config struct that drives the entire workflow.

The entry point in [src/main.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/main.rs) invokes the launch function defined in [src/generator/workflow.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/workflow.rs), passing the configuration to initiate the pipeline.

Stage 2: Pre-processing and Code Extraction

The PreProcessAgent::execute function in [src/generator/preprocess/mod.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/preprocess/mod.rs) walks the project tree and reads every .rs file. It delegates language-specific parsing to the Rust processor located in [src/generator/preprocess/extractors/language_processors/rust.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/preprocess/extractors/language_processors/rust.rs).

Rust Language Processing

The Rust extractor uses regex patterns to locate use, mod, fn, struct, enum, trait, and impl declarations. It produces structured data in the form of Dependency and InterfaceInfo structs, capturing imports, module hierarchies, and function signatures.

All extracted structures are stored under MemoryScope::PROJECT_STRUCTURE in the global Memory system defined in [src/memory/mod.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/memory/mod.rs), making them available to downstream agents via DataSource::PROJECT_STRUCTURE and DataSource::CODE_INSIGHTS.

Stage 3: Research Orchestration and C4 Analysis

The ResearchOrchestrator in [src/generator/research/orchestrator.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/research/orchestrator.rs) instantiates specialized research agents that analyze the extracted code through LLM prompts. Each agent receives the code insight payload and produces JSON reports aligned with C4 model specifications defined in [src/generator/research/types.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/research/types.rs).

System Context Research

The SystemContextResearcher in [src/generator/research/agents/system_context_researcher.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/research/agents/system_context_researcher.rs) builds a PromptTemplate with a system prompt describing a C4 analyst role. It invokes the LLM in LLMCallMode::Extract mode to generate a JSON object conforming to the C4 System Context schema, identifying business value, target users, and system boundaries.

Stage 4: Documentation Composition

The composer stage, centered in [src/generator/compose/mod.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/mod.rs), consumes the JSON research reports and runs composer agents that craft final markdown files. These agents pull data via DataSource::ResearchResult(...) and use LLMCallMode::Prompt to generate C4-compliant documentation.

Generating System Context Diagrams

The OverviewEditor in [src/generator/compose/agents/overview_editor.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/agents/overview_editor.rs) acts as the C4 System Context writer. Its system prompt declares: "You are a professional software architecture documentation expert, focused on generating C4 architecture model..." The agent returns markdown containing Mermaid syntax for system-context diagrams, describing external interactions and user boundaries.

Generating Container Views

The ArchitectureEditor in [src/generator/compose/agents/architecture_editor.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/compose/agents/architecture_editor.rs) handles the C4 Container level. It analyzes the module structure extracted from src/ directories and generates container diagrams showing high-level technology choices and inter-container communication patterns.

Data Flow and Memory Management

The entire pipeline relies on the Memory system in [src/memory/mod.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/memory/mod.rs) to share state between agents. The LLM client abstraction in [src/llm/client/mod.rs](https://github.com/sopaco/deepwiki-rs/blob/main/src/llm/client/mod.rs) handles model selection and API communication, supporting both efficient and powerful model configurations specified via CLI arguments.

Running Litho on Your Rust Project

To generate C4 documentation for your own Rust codebase, install and run the Litho CLI:

# Install the binary

cargo install --git https://github.com/sopaco/deepwiki-rs litho

# Generate C4 documentation for a local crate

litho \
  --project-path ./my_rust_app \
  --output-path ./my_rust_app/docs \
  --model-efficient llama3:8b \
  --model-powerful llama3:70b \
  --verbose

The CLI parses arguments defined in src/cli.rs and initiates the workflow in src/generator/workflow.rs, ultimately producing markdown files including Project_Overview.md (System Context) and Architecture_Overview.md (Container View).

Sample Output: System Context Documentation

When Litho processes a Rust web service, it generates Project_Overview.md containing the C4 System Context view:

# System Context Overview

## 1. Project Introduction

- **Project name**: my_rust_app
- **Description**: A high‑performance web service written in Rust.
- **Core value**: Low‑latency request handling for real‑time analytics.

## 2. Target Users

- Backend engineers integrating the API.
- Data scientists consuming streaming analytics.

## 3. System Boundaries

- **In‑scope**: `src/main.rs`, `src/api/*`, `src/processor/*`
- **Out‑of‑scope**: External monitoring agents, legacy DB adapters.

## 4. External System Interactions

- **PostgreSQL** (via `sqlx`)
- **Kafka** (via `rdkafka`)
- **Auth Service** (OAuth2)

## 5. System Context Diagram

```mermaid
graph LR
    User[User] -->|HTTPS| API[API Server]
    API -->|SQL| DB[(PostgreSQL)]
    API -->|Kafka| Kafka[(Kafka Cluster)]
    API -->|OAuth| Auth[(Auth Service)]

This output is produced by the `OverviewEditor` agent, whose prompt explicitly requests C4 SystemContext diagram format.

## Sample Output: Architecture Container View

For the Container level, Litho generates [`Architecture_Overview.md`](https://github.com/sopaco/deepwiki-rs/blob/main/Architecture_Overview.md):

```markdown

# Architecture Overview

## 1. Architecture Overview

The service follows a **Hexagonal** architecture with clear separation between the **API** (port), **Domain** (core business logic), and **Infrastructure** (adapters).

## 2. Project Structure

my_rust_app/ ├─ src/ │ ├─ api/ # HTTP handlers (actix‑web)

│ ├─ domain/ # Core business rules

│ ├─ infrastructure/ │ │ ├─ db.rs # PostgreSQL adapter

│ │ └─ kafka.rs # Kafka producer/consumer

│ └─ main.rs

## 3. Container View

```mermaid
containerDiagram
    container API {
        component "HTTP Router" as Router
        component "Auth Middleware" as Auth
    }
    container "Domain Layer" {
        component "Processor" as Processor
    }
    container "Infrastructure" {
        component "Postgres Adapter" as PG
        component "Kafka Adapter" as Kafka
    }

    Router --> Processor
    Processor --> PG
    Processor --> Kafka

4. Component View

• Router – Parses requests, validates auth, forwards to Processor.
• Processor – Executes business rules, orchestrates DB and event writes.
• PG Adapter – Handles async DB queries via sqlx.
• Kafka Adapter – Publishes events using rdkafka.

5. Deployment View

• Deployed as a Docker container on Kubernetes.
• Horizontal pod autoscaling based on request latency.

This content is generated by the `ArchitectureEditor` agent targeting the C4 Container level.

## Summary

- **Litho** automates C4 model documentation generation through a four-stage pipeline implemented in the `sopaco/deepwiki-rs` repository.
- **Pre-processing** extracts Rust code semantics using regex-based parsing in [`src/generator/preprocess/extractors/language_processors/rust.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/preprocess/extractors/language_processors/rust.rs), storing results as `Dependency` and `InterfaceInfo` structs.
- **Research agents** like `SystemContextResearcher` analyze code insights via LLM prompts in `LLMCallMode::Extract` to produce JSON reports aligned with C4 schemas.
- **Composer agents** including `OverviewEditor` and `ArchitectureEditor` transform research data into markdown documentation with Mermaid diagrams using `LLMCallMode::Prompt`.
- The entire workflow is coordinated through [`src/generator/workflow.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/workflow.rs) with shared state managed via the `Memory` system in [`src/memory/mod.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/memory/mod.rs).

## Frequently Asked Questions

### How does Litho extract information from Rust source files?

Litho uses a dedicated Rust language processor located in [`src/generator/preprocess/extractors/language_processors/rust.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/generator/preprocess/extractors/language_processors/rust.rs). This processor employs regex patterns to identify `use` statements, `mod` declarations, `fn` signatures, `struct`, `enum`, `trait`, and `impl` blocks. It constructs `Dependency` and `InterfaceInfo` structs that capture the module hierarchy and type relationships, storing them in the global `Memory` under `MemoryScope::PROJECT_STRUCTURE`.

### What C4 model levels does Litho generate?

Litho generates documentation for C4 Level 1 (System Context) and C4 Level 2 (Container). The `SystemContextResearcher` and `OverviewEditor` handle Level 1 by identifying external systems, users, and business boundaries. The `ArchitectureEditor` handles Level 2 by mapping the internal container structure, technology choices, and inter-container communication patterns. The prompts explicitly request Mermaid diagram syntax for these C4 views.

### Which LLM modes does Litho use during documentation generation?

Litho utilizes two distinct LLM invocation modes defined in the client abstraction. During the research phase, it uses `LLMCallMode::Extract` to force structured JSON output conforming to C4 schemas (e.g., when `SystemContextResearcher` analyzes code). During the composition phase, it uses `LLMCallMode::Prompt` to generate free-form markdown documentation with Mermaid diagrams (e.g., when `OverviewEditor` or `ArchitectureEditor` craft the final output).

### How can I customize the output path and LLM models when running Litho?

You can configure Litho through command-line arguments defined in [`src/cli.rs`](https://github.com/sopaco/deepwiki-rs/blob/main/src/cli.rs). Use `--project-path` to specify the Rust codebase location and `--output-path` to set the documentation destination. For model selection, use `--model-efficient` for lighter tasks and `--model-powerful` for complex analysis. For example: `litho --project-path ./my_app --output-path ./docs --model-efficient llama3:8b --model-powerful llama3:70b`.

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