repo-architect

Your codebase, documented. Automatically. Every night.

repo-architect scans your repository, analyzes it with Claude, and generates architecture documentation with Mermaid diagrams — system maps, data flows, dependency graphs, and per-module docs.

Quick Start

npx repo-architect

Or with Bun:

bunx repo-architect

You'll need an Anthropic API key. Set it via environment variable or config file:

export ANTHROPIC_API_KEY=sk-ant-...
# or save to ~/.repo-architect

What You Get

docs/architecture/
├── OVERVIEW.md          # System map, tech stack, data flows, dependency graph
└── modules/
    ├── api.md           # Per-module docs with class diagrams
    ├── auth.md
    └── ...

All diagrams use Mermaid syntax — renders natively on GitHub.

Usage

# Full scan (default for first run)
npx repo-architect

# Incremental update (only re-analyzes structural changes)
npx repo-architect --incremental

# Create a PR with the generated docs
npx repo-architect --pr

# View docs locally in the browser
npx repo-architect --view

# Set up a GitHub Action for nightly runs
npx repo-architect --setup

# Specify a different repo directory
npx repo-architect --dir /path/to/repo

Incremental Updates

After the first full scan, repo-architect tracks state in docs/architecture/.arch-state.json. On subsequent runs with --incremental, it only re-analyzes files with structural changes (new/modified/deleted code files, config changes) and patches the existing docs.

GitHub Action

Run npx repo-architect --setup to generate a workflow file that:

• Runs on a cron schedule (default: 3am daily)
• Detects structural changes since the last run
• Updates architecture docs
• Opens a PR with the changes

You'll need to add ANTHROPIC_API_KEY as a repository secret.

Local Viewer

npx repo-architect --view

Opens an interactive HTML viewer at http://127.0.0.1:3333 with:

• Dark theme
• Sidebar navigation
• Mermaid diagram rendering with zoom/pan controls
• Responsive layout

Homepage

repo-architect.com

License

MIT