LLitho / deepwiki-rs
01 / 18
CODEBASE → ARCHITECTURE WIKI

Make the codebase legible.

A deep dive into Litho, the Rust CLI formerly known as deepwiki-rs. It analyses a repository, asks specialised agents to make sense of it, and writes a structured C4 documentation set.

Source snapshot: 14 September 2026 · commit 27dbd3e
src/docs/configscanC1C2C3–4wiki filescontextresearchoutput
“High-performance AI-driven intelligent document generator” · README.md01 / COVER

In plain English

Litho turns a messy repository into a navigable explanation of how the system works.

01 / INGEST

Read the repository

Walk the project, extract structure, inspect language-specific patterns, and retain original documentation material.

02 / REASON

Build an architecture view

Specialised research agents work from shared context to infer system, domain, workflow, module, and boundary views.

03 / WRITE

Export a Repo-Wiki

Compose Markdown documentation with C4 diagrams, relationships, code-level notes, and a summary report.

The useful mental model: a documentation compiler with LLM-powered analysis passes.

The README describes a four-stage pipeline: preprocessing → research → composition → verification/output · README.md02 / TL;DR

Documentation decays. Code keeps moving.

Litho is designed for the awkward gap between what a codebase does and what the team can still explain.

The payoff is not “more docs”. It’s less archaeology.

New teammates find the shape of the system sooner. Reviewers get architectural context. Maintainers get a repeatable baseline that can be regenerated after change.

Without a generator

  • Important context lives in people’s heads.
  • Manual diagrams drift away from implementation.
  • Every onboarding question becomes a bespoke tour.

With Litho in the loop

  • Repository structure becomes a shared starting point.
  • C4 views give the team a common abstraction ladder.
  • Cacheable, repeatable passes make refreshes cheaper.
Benefits are stated by the project as onboarding, code review, compliance, multi-language support, and CI/CD suitability · README.md03 / WHY

Where it earns its keep

Use Litho when the cost of understanding a system is higher than the cost of generating a first architectural map.

GOOD FIT / NOT A RUNTIME OBSERVER

It is a read-only analysis and documentation tool. It doesn’t replace design judgement, tests, production observability, or human review.

↳ 01

Onboard a new engineer

Start with the generated system context, architecture, workflow, and boundary documents before diving into individual modules.

↳ 02

Prepare a code review

Regenerate a lightweight architecture baseline to make large refactors easier to discuss.

↳ 03

Preserve institutional knowledge

Capture what the current code implies before a team, product, or ownership boundary changes.

↳ 04

Bring business context closer

Mount local Markdown, PDF, SQL, YAML, or JSON knowledge and route it to the agents that need it.

The repository explicitly positions itself for developers, architects, technical writers, engineering teams, and open-source projects · README.md04 / USE CASES

Understand
the machine.

The interesting part isn’t the CLI wrapper. It’s the chain of specialised passes, shared state, and controlled LLM calls underneath it.

Deep dive: execution flow, agent contracts, LLM integration, memory, cache, and outputs.05 / SECTION BREAK

A staged pipeline, not one giant prompt

Each phase produces structured material for the next. That makes the process easier to inspect, resume, cache, and evolve.

01 / PRE

Preprocess

Repository structure, source material, directory dossiers, and relationships.

02 / C1–4

Research

System, domain, architecture, workflow, module, boundary, and optional database analysis.

03 / DOC

Compose

Specialised editors turn research into a documentation tree.

04 / OUT

Output

Write Markdown, summary information, and run Mermaid repair.

PHASE 01PreprocessPHASE 02ResearchPHASE 03ComposePHASE 04OutputSHARED CONTEXTMemory + cacheOUTPUT TREEC4 Markdown
`launch()` creates the context, optionally syncs knowledge, then runs preprocessing → research → composition → output · workflow.rs06 / PIPELINE

First, make the repository inspectable.

Before an agent tries to explain the system, Litho builds a compact working representation of it.

$ deepwiki-rs -p ./my-project

▾ project_structure
├─ directories
├─ files
└─ tracked metadata
▾ directory_dossiers
├─ purpose + summary
├─ file insights
└─ importance score
▾ relationships
└─ module / file links
12language processors are registered in the source tree, including Rust, Python, JavaScript, TypeScript, React, Vue, Swift, Kotlin, PHP, C#, Java, and Svelte.
256 KBmaximum directory content batch before the preprocessor splits work at file boundaries.
read-onlythe analysis reads source and writes documentation/cache artefacts. It doesn’t operate on the target system at runtime.
fallbacks existif an LLM directory summary fails, the preprocessor can keep a fallback dossier and continue its pipeline.
Preprocessing implementation: structure extraction, directory dossiers, batching, and relationship analysis · preprocess/mod.rs · language processors07 / PREPROCESS

Research zooms in, layer by layer.

The research stage moves from “what is this system?” towards “what are the important modules and boundaries?”

C1 / system context01

SystemContextResearcher frames the project and its users.

C2 / containers & domains02–04

DomainModulesDetector, ArchitectureResearcher, and WorkflowResearcher map the meso level.

C3–C4 / modules & boundaries05–06

KeyModulesInsight and BoundaryAnalyzer deepen the code-level and interface view.

RESEARCH ORCHESTRATOR / DEFAULT PATH
SystemContextResearcherproject purpose, audience, system boundary
DomainModulesDetectordomain module candidates and importance
ArchitectureResearcherarchitecture structure and relationships
WorkflowResearcherhow work moves through the system
KeyModulesInsightdeep insight into key modules
BoundaryAnalyzerCLI, API, router, and configuration boundaries
DatabaseOverviewAnalyzerconditional: runs when database-related files are detected
The orchestrator runs six core analyses and conditionally adds database analysis · research/orchestrator.rs08 / RESEARCH

Every agent signs a small contract.

The StepForwardAgent trait turns each analysis pass into a repeatable unit: declare inputs, build a prompt, choose an execution mode, validate the output, and store the result.

DATArequired and optional sources from memory, research, or local knowledge
MODEstructured extraction, free-form prompting, or prompting with tools
FORMATtoken-aware project structure, insights, dependencies, README material
RESULTtyped output, formatted summary, and a memory write

Structured output

The agent asks the provider for a typed result that can be deserialised against a JSON schema. This is useful when the next stage depends on predictable fields.

LLMCallMode::Extract JsonSchema + Deserialize
Agent data sources, call modes, formatter configuration, and execution abstraction · step_forward_agent.rs · agent_executor.rs09 / AGENT CONTRACT

One client, several model backends.

The provider layer keeps the rest of the generator focused on prompts and data, while the CLI can select cloud-compatible or local inference.

openaianthropicgeminideepseekmoonshotmistralopenrouterollama
Pick a model by prompt size

Efficient and powerful model settings are evaluated before a call.

Retry with backoff

Transient provider errors can be retried; a powerful model can serve as a fallback.

Use ReAct when exploration helps

Research agents can call preset file explorer, file reader, and time tools.

agent: ResearchOrchestrator
mode: PromptWithTools
tools: [
file_explorer,
file_reader,
time
]

if max_depth → summary_reasoner
if provider fails → retry / fallback

The tool boundary matters: file tools apply whitelist and path checks, so the model isn’t given an unrestricted filesystem primitive.

Provider enum, agent construction, tool wiring, retry logic, and summary fallover · providers.rs · client/mod.rs10 / LLM + TOOLS

Shared context keeps the passes connected.

GeneratorContext carries the LLM client, configuration, cache manager, and in-memory store across the pipeline.

PREPROCESS scope

Project structure, code insights, original document, relationships.

RESEARCH scope

Typed agent reports that downstream editors can retrieve.

DOCUMENTATION scope

Markdown sections held by the documentation tree before output.

// cache key = category + MD5(prompt)
cache.get(category, prompt)
↳ hit: deserialize JSON
↳ miss: call provider
cache.set(category, prompt, data)
// tracks hits, misses, writes, errors
// token and estimated cost savings

--no-cache disable cache
--force-regenerate clear cache safely

The cache is file-based and expiry-aware. It improves repeatability and can reduce duplicate model calls, but a cache hit is only as good as the prompt and source snapshot that produced it.

Context wiring and scoped memory · context.rs · prompt-hash cache and performance metrics · cache/mod.rs11 / MEMORY + CACHE

Research becomes a documentation tree.

Composition uses specialised editors to write the views a human reader needs, then the outlet persists them in the target language’s file naming scheme.

litho.docs/
├─ 1.Overview.md
├─ 2.Architecture.md
├─ 3.Workflow.md
├─ 5.Boundary-Interfaces.md
├─ 6.Database-Overview.md (if detected)
└─ summary.json / report

One useful finishing move

After writing the Markdown, Litho invokes mermaid-fixer to detect and repair generated Mermaid syntax. That dependency is checked at startup, so a missing fixer stops the run early.

This is a good example of a generator treating its own output as something to validate, not just something to emit.

Six composition editors, language-aware DocTree, disk output, summary outlet, and Mermaid fixer integration · compose/mod.rs · outlet/mod.rs12 / OUTPUT

Implement
the loop.

The fastest path is to get one project through the full pipeline, inspect the output, then tune the model, knowledge, and cache decisions.

Implementation guide: install, configure, run, validate, and iterate.13 / SECTION BREAK

Get a first map in one session.

Use this as a deliberate first pass. Don’t begin by perfecting every setting.

Install and run

cargo install deepwiki-rs
deepwiki-rs -p ./my-project -o ./litho.docs
deepwiki-rs --target-language en -p ./my-project

The CLI defaults to the current directory and ./litho.docs if you omit paths.

Prerequisites, install options, and basic commands · README.md · cli.rs14 / QUICK START

Configure the decisions, not the noise.

Start with the example TOML. The high-impact choices are provider, endpoint, model pairing, concurrency, target language, cache, and local knowledge.

[llm]
provider = "ollama"
api_base_url = "http://localhost:11434"
model_efficient = "your-fast-model"
model_powerful = "your-strong-model"

[cache]
enabled = true
expire_hours = 24

target_language = "en"

Cloud or local?

Use a compatible hosted endpoint for stronger models, or Ollama where local inference and data locality matter more.

Fast model or strong model?

Keep routine extraction efficient, then reserve the powerful model for complex reasoning and fallback.

Fresh run or cache-assisted run?

Use the cache while iterating. Use --force-regenerate when you need to invalidate prior LLM responses.

Code only or code + knowledge?

Mount ADRs, architecture docs, SQL, API specs, and business context when code alone can’t explain intent.

Configuration schema and example values · litho-example.toml · CLI overrides · config.rs15 / CONFIGURE

Give the agents the context code can’t contain.

Local knowledge integration lets you classify and chunk supporting documents, cache them, and route relevant categories to selected agents.

Good candidates: ADRs, API contracts, database schemas, deployment notes, workflows, and domain glossaries.
[knowledge.local_docs]
enabled = true
cache_dir = ".litho/cache/knowledge"

[[categories]]
name = "architecture"
paths = [
"docs/architecture/**/*.md",
"docs/design/**/*.pdf"
]
target_agents = [
"ArchitectureResearcher",
"ArchitectureEditor"
]
deepwiki-rs sync-knowledge --force
Supported document types, categories, chunking, sync behaviour, and agent filtering · README.md · knowledge_sync.rs16 / KNOWLEDGE

Trust the map by testing its edges.

Generated documentation is a useful starting point, not ground truth. Validate what it says against the source and the team’s intent.

A PRACTICAL REVIEW LOOP

Compare the generated system context with the README. Trace one workflow into the files. Check one boundary against the CLI/config. Record what the generator missed.

Strength
Clear abstraction ladder

C1 → C2 → C3/C4 gives readers a route from system intent to implementation detail.

Strength
Resumable ingredients

Typed outputs, memory scopes, and cache entries make intermediate work inspectable.

Strength
Local inference option

Ollama support is useful when a project needs a local model boundary.

Watch
LLM inference is still inference

Architecture roles and relationships can be plausible but wrong. Cross-check consequential claims.

Watch
Docs can drift between runs

Regeneration improves freshness, but it doesn’t prove correctness or preserve every human decision.

Watch
Large repos need tuning

Prompt compression, directory-only formatting, concurrency, and cache settings affect cost and quality.

Limitations here are reasoned recommendations grounded in the repository’s read-only boundary, LLM dependence, cache, and large-project controls · generated overview · config.rs17 / VALIDATE

The short version.

Litho is a focused, local-first-feeling architecture documentation engine. Its value comes from the workflow around the model: inspectable phases, typed hand-offs, scoped memory, caching, and output repair.

END / BEGIN WITH ONE REPOSITORY
01

Use it to lower the cost of understanding. Start with onboarding, review, or knowledge preservation.

02

Think like a compiler. The pipeline is the product: preprocess, research, compose, output.

03

Keep humans in the loop. Generated architecture is evidence to inspect, not a substitute for ownership.

04

Pair code with intent. Add ADRs, contracts, and domain context when the repository can’t speak for itself.

Primary source: github.com/sopaco/deepwiki-rs · The README notes that Litho has evolved into Terrain; this deck focuses on the Litho / deepwiki-rs repository snapshot and its focused C4 generator.

Built from repository README, source modules, configuration example, generated English docs, and MIT licence.18 / TAKEAWAYS
← → navigate · O overview · F fullscreen