repoarch 🗺️

Turn any codebase into beautiful architecture diagrams — one command, no AI, no server, runs on any laptop.

Drop in a folder, get a clean, shareable architecture map. Zero dependencies. Pure Python stdlib. Works offline on a Raspberry Pi, a 2015 laptop, or a cloud VM — Mermaid + self-contained HTML that opens in any browser.

↓ generated from the sample/ project in this repo, in < 1 second ↓

---

✨ Features

🗂️ 4 output formats	interactive HTML, Mermaid .mmd, Graphviz .dot, structured JSON
🌍 14 languages	Python · Go · JS/TS · Java · Rust · Ruby · PHP · C/C++ · C# · Kotlin · Swift · Dart
📊 Graph metrics	density, average degree, and core/backbone component ranking
⚙️ Config file	.repoarch for repeatable, project-specific runs
🔍 Smart scanning	gitignore-aware, --exclude, --lang, --min-degree filters
🎛️ Flow control	LR / TB / RL / BT layout, plus live edit + fullscreen in HTML
🤖 Agent-ready	installs as a skill for Cursor, Claude Code, Codex, and OpenCode
💸 100% free	zero dependencies, no AI, no server, no API keys, runs on any laptop

✨ Why repoarch

• No AI. No API keys. No paid services. Runs offline forever — your code never leaves your machine.
• No server. Output is a single self-contained HTML file you can email, open, or host anywhere.
• Zero dependencies. Pure Python standard library — installs in literally one command, works everywhere.
• Any language. Python, Go, JS/TS, Java, Rust, Ruby, PHP, C/C++, C# — detected automatically.
• Instant. Scans and renders a project in under a second.
• Agent-friendly. Works great as a tool for Cursor, Claude Code, Codex, and OpenCode.

🔧 Install

# one line, no dependencies
pip install repoarch

Or run without installing anything:

# clone this repo, then:
python -m repoarch /path/to/your/codebase

🐳 Docker

Pre-built images are published to the GitHub Container Registry (ghcr.io/dsk-dev-ai/repoarch) on every release. Pull, point it at any folder, and never install Python:

docker pull ghcr.io/dsk-dev-ai/repoarch:1.0.0   # or :latest

# map a folder to ./out and read the HTML
docker run --rm -v "$PWD:/app" \
  ghcr.io/dsk-dev-ai/repoarch:latest /app -o /app/out
# -> /app/out/architecture.html

🤖 Agent skill (Cursor · Claude Code · Codex · OpenCode)

Works as a first-class skill in your favorite AI coding agent — ask it to "map this repo" and get a verified architecture diagram.

# one-command install for all agents (or: cli, cursor, claude, codex, opencode)
./install.sh all

# or use archify-style agent skill install
npx skills add dsk-dev-ai/repoarch

Then just tell your agent:

Use repoarch to map this repository's architecture.

🚀 Quick start

# generate diagrams for any folder
repoarch /path/to/codebase -o out/

# open the result in your browser
open out/architecture.html          # macOS
xdg-open out/architecture.html      # Linux
start out/architecture.html         # Windows

Output:

File	What it is
architecture.html	Interactive, self-contained diagram (dark/light, zoom, live edit)
architecture.mmd	Raw Mermaid source
architecture.dot	Graphviz dot source for external tools
architecture.json	Structured component / edge / metric metadata

🛠️ Options

repoarch path [options]

Flag	Description
-o, --output	Where to write the files (default: .)
--name	Custom diagram title (default: folder name)
--min-degree N	Hide low-importance components to declutter large projects
-x, --exclude	Path(s) to exclude (repeatable), e.g. -x tests -x docs
--lang	Only include these languages (repeatable), e.g. --lang python --lang go
-d, --direction	Flow direction: LR (default), TB, RL, BT
--format	Outputs to write: all (default), html, mmd, json, dot
-c, --config	Path to a .repoarch config file (auto-detected by default)
--no-gitignore	Do not honor .gitignore during the scan
--json	Write architecture.json metadata (implied by --format json/all)
--version	Print version and exit

Example

# plot only Python + Go, left-to-right, include metrics
repoarch ./myapp -o out --lang python --lang go -d LR --format all

# use a config file, declutter
repoarch ./bigrepo -c .repoarch --min-degree 2

🧠 How it works

1. Scan — walks the folder, skips .git, node_modules, venv, and other noise.
2. Classify — detects the language of every source file by extension.
3. Extract — parses import / require / using statements per language (regex, stdlib only).
4. Group — maps files to top-level components.
5. Score — ranks components by how central they are to the system.
6. Render — emits Mermaid + a self-contained HTML viewer.

🗺️ Language support

Python · Go · JavaScript · TypeScript · Java · Rust · Ruby · PHP · C · C++ · C# · Kotlin · Swift · Dart

📊 Metrics

With --format all or --json, repoarch reports graph metrics in architecture.json:

• Density — how connected the module graph is
• Average degree — mean in/out edges per component
• Core components — the modules with the most relationships (your real architecture backbone)
• Top components — ranked by importance

🤝 Contributing

Issues, pull requests, and real-world diagrams are welcome. Want to add a language? It's one entry in repoarch/parser.py.

❤️ Sponsors

repoarch is free, open source, and has zero dependencies and zero running costs to stay that way. If it saves you time, consider sponsoring the project — every bit helps keep it free forever.

Support free, local-first dev tools

Want to sponsor repoarch or list your product here? Open an issue.

⭐ Support

If repoarch saved you an hour of diagram-drawing, give it a star ⭐ — it helps more developers find it.

📄 License

MIT — free to use, modify, and distribute.