archmap

Generate a single, self-contained interactive architecture-map HTML from any project's source code.

archmap scans a project folder, infers its architectural layers, extracts modules / classes / functions / imports, resolves the dependency graph between files, and renders everything into one standalone HTML file — no server, no build step, no external assets.

archmap <project_folder_path>

Open the generated *-architecture.html in any browser and explore your codebase through five tabs.

Features

• 📊 Overview — file/line/class/function counts, language breakdown, and a layer distribution chart.
• 🏗️ Architecture Layers — every file grouped into inferred layers (Entry Points, Config, Models, API, Services, Data Access, Integrations, UI, Utilities, Tests, Docs, Build/Ops).
• 🔗 Dependencies — internal import relationships resolved between in-project files, with "depends on" / "used by" edges.
• 📁 File System — a collapsible tree of everything scanned, each file clickable.
• 🔎 Component Reference — a searchable table of all components.
• A detail side-panel for any component: layer, language, line count, classes, functions, methods, imports, and dependency links.

Everything is embedded in a single HTML file (data is inlined as JSON), so it is trivial to share, archive, or commit.

Installation

archmap is pure Python with zero runtime dependencies. Pick whichever fits.

Standalone binary (no Python needed)

Download the executable for your platform from the latest release, then run it directly:

# Linux / macOS
chmod +x archmap-linux-x86_64
./archmap-linux-x86_64 /path/to/project

# Windows
.\archmap-windows-x86_64.exe C:\path\to\project

pipx (recommended if you have Python 3.8+)

Installs into an isolated environment and puts archmap on your PATH:

pipx install archmap-cli                                   # from PyPI (provides the `archmap` command)
pipx install git+https://github.com/heiswayi/archmap       # from GitHub

pip

pip install archmap-cli        # from PyPI (provides the `archmap` command)
pip install .                  # from a source checkout

Requires Python 3.8+ (except the standalone binaries, which bundle their own runtime).

Usage

# Scan the current directory
archmap .

# Scan a specific project and open the result in your browser
archmap /path/to/project --open

# Custom output path and display name
archmap /path/to/project -o report.html --name "My Service"

# Ignore .gitignore rules while scanning
archmap /path/to/project --no-gitignore

The output HTML path is also printed to stdout so it can be piped.

How it works

1. Scan (scanner.py) — walks the tree, skipping common noise (.git, node_modules, build dirs, lockfiles, binaries) and honoring .gitignore.
2. Analyze (languages/) — Python files are parsed with the standard-library ast; other languages (JS/TS, Go, Rust, Java, Ruby, C/C++, …) are read with language-aware regex heuristics to pull out classes, functions, and imports.
3. Classify (layers.py) — each file is routed into an architectural layer using directory- and filename-based scoring.
4. Link (analyzer.py) — raw imports are resolved against in-project files to build the dependency graph (both dotted module paths and relative file paths).
5. Render (renderer.py) — the model is serialized to JSON and injected into a single HTML template.

Supported languages

Python (deep ast analysis), JavaScript, TypeScript, Go, Rust, Java, Kotlin, Ruby, PHP, C#, Swift, C/C++, Shell, Vue, Svelte, plus structural files (YAML, TOML, JSON, Markdown, Dockerfile, Terraform, …).

License

MIT