repo-explain

Point it at any codebase, get instant architectural docs

Comment

Repo Explainer

Inspiration

Every developer knows the pain of onboarding to a new codebase. You clone the repo, stare at hundreds of files, and spend days—sometimes weeks—just trying to understand how things connect. Where's the entry point? What calls what? What patterns are being used?

We asked ourselves: What if AI could give you the architectural map instantly? Not just a file listing, but real understanding—component relationships, data flows, tech stack decisions, and visual diagrams that make it all click.

What it does

Repo Explainer is a CLI tool that analyzes any repository (local or remote) and generates comprehensive, beautiful architecture documentation in minutes.

Point it at any codebase:

repo-explain analyze https://github.com/kubernetes/kubernetes --depth deep

And get:

  • 📚 Coherent documentation with index.md as your starting point
  • 📊 Mermaid diagrams (components + data flow) auto-rendered to SVG
  • 🏗️ Architecture breakdowns with file-to-component mappings
  • 🔍 Pattern detection (MVC, microservices, repository pattern, etc.)
  • 📦 Tech stack analysis with dependency graphs
  • 🔗 Function-level traceability with line numbers

It works on public repos, private repos (via SSH), or any local directory. No manual setup—just one command.

How we built it

Core Stack:

  • Python with Rich CLI for beautiful terminal output
  • OpenCode AI as the analysis engine (configurable LLM backend)
  • Mermaid CLI for diagram rendering
  • Git integration for automatic cloning and caching

Architecture:

  1. Repository Loader – Handles local paths, HTTPS URLs, and SSH URLs. Smart caching so subsequent runs are instant.
  2. OpenCode Service – Orchestrates AI analysis with specialized prompts for different depths (quick/standard/deep/extra-deep).
  3. Prompt System – Modular templates (quick_scan_v2, architecture_deep_dive, pattern_detection, dependency_mapping) designed for token efficiency and accurate file-to-component mapping.
  4. Doc Composer – Transforms raw analysis into navigable Markdown with cross-linked pages.
  5. Diagram Renderer – Renders Mermaid to SVG with auto-fix for syntax errors.

Key Design Decision: We enforce that every component cites its source file and line ranges. This makes the docs actually useful—you can jump straight from the architecture diagram to the exact code.

Challenges we ran into

1. Mermaid Syntax Errors from AI

LLMs sometimes generate invalid Mermaid syntax. We built an auto-fix loop that detects rendering failures, sends the error back to the AI for correction, and retries up to 2 times. Works surprisingly well.

2. Token Efficiency for Large Repos

Analyzing Kubernetes (2M+ lines) can't send everything to the LLM. We developed a progressive analysis strategy: quick scan for inventory → targeted deep dives on key components → synthesis. The prompt system explicitly guides the AI on which files to read.

3. File-to-Component Mapping Accuracy

Early versions would say "there's an auth module" without saying where. We redesigned prompts with strict output schemas requiring file_path and line_range for every component and function. Now everything is traceable.

4. Remote Repository Handling

Supporting HTTPS, SSH, and local paths with proper caching, force-refresh options, and owner/repo directory structure took iteration to get right.

Accomplishments that we're proud of

  • ✅ One-command analysis of any repository—no config files needed
  • ✅ Actually useful output — not walls of text, but navigable docs with diagrams
  • ✅ Self-documenting accuracy — we ran repo-explain on itself and validated the output
  • ✅ Auto-fix for diagram errors — graceful degradation when AI makes mistakes
  • ✅ Evidence-based assertions — every claim links back to specific files and lines
  • ✅ Works on massive codebases — tested on Kubernetes, React, Linux kernel (quick scan)
  • ✅ Beautiful CLI UX — Rich progress indicators, verbose mode for transparency, colored output

What we learned

1. Prompt Engineering is Architecture

The quality of output is 80% prompt design. Investing in explicit output schemas, validation checklists, and few-shot examples in prompts made a massive difference.

2. AI Needs Guardrails

LLMs hallucinate. Requiring file paths and line numbers forces the AI to ground its analysis in actual code. "Show your work" improves accuracy.

3. Progressive Disclosure Works

Users don't want 50 pages upfront. Starting with index.md that links to subsections, with diagrams embedded, matches how developers actually explore.

4. The 80/20 of Codebase Understanding

For most repos, understanding the entry points, main components, and data flow covers 80% of what you need to get started. We optimized for that.

What's next for repo-explain

Near-term:

  • 🔄 Incremental analysis — only re-analyze changed files
  • 🌐 HTML output — interactive, searchable documentation site
  • 🔗 Multi-repo analysis — understand how microservices connect
  • 📝 Custom prompts — bring your own analysis templates

Medium-term:

  • 🧩 IDE integrations — VS Code extension for inline architecture hints
  • 🤖 CI/CD integration — auto-generate docs on every merge
  • 📈 Historical analysis — track architectural evolution over time

Long-term:

  • 🎯 Onboarding copilot — "Explain how authentication works in this repo"
  • 🔍 Code review assistant — "Does this PR violate existing patterns?"
  • 🌍 Public repo index — searchable architecture docs for popular open source

Our vision: Make "understanding code" as easy as "running code." Every developer should be able to grok any codebase in minutes, not days.

Built With

Share this project:

Updates