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

✨ 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

🤖 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:

🛠️ Options

repoarch path [options]

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.