https://github.com/heiswayi/archmap
Generate a single, self-contained interactive architecture-map HTML from any project's source code.
https://github.com/heiswayi/archmap
architecture architecture-visualization cli code-visualization dependency-graph developer-tools documentation-tool python static-analysis
Last synced: 11 days ago
JSON representation
Generate a single, self-contained interactive architecture-map HTML from any project's source code.
- Host: GitHub
- URL: https://github.com/heiswayi/archmap
- Owner: heiswayi
- License: mit
- Created: 2026-06-16T12:43:30.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-17T04:02:15.000Z (about 1 month ago)
- Last Synced: 2026-06-17T06:03:44.643Z (about 1 month ago)
- Topics: architecture, architecture-visualization, cli, code-visualization, dependency-graph, developer-tools, documentation-tool, python, static-analysis
- Language: Python
- Homepage:
- Size: 34.2 KB
- Stars: 3
- Watchers: 0
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.
```bash
archmap
```
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](https://github.com/heiswayi/archmap/releases/latest), then run it directly:
| Platform | Asset |
| --- | --- |
| Linux (x86_64) | `archmap-linux-x86_64` |
| macOS (Apple Silicon) | `archmap-macos-arm64` |
| macOS (Intel) | `archmap-macos-x86_64` |
| Windows (x86_64) | `archmap-windows-x86_64.exe` |
```bash
# Linux / macOS
chmod +x archmap-linux-x86_64
./archmap-linux-x86_64 /path/to/project
```
```powershell
# 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:
```bash
pipx install archmap-cli # from PyPI (provides the `archmap` command)
pipx install git+https://github.com/heiswayi/archmap # from GitHub
```
### pip
```bash
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
```bash
# 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
```
| Flag | Description |
| --- | --- |
| `path` | Project folder to scan (default: `.`). |
| `-o, --output` | Output HTML path (default: `-architecture.html`). |
| `-n, --name` | Project name shown in the report (default: folder name). |
| `--open` | Open the report in the default browser when done. |
| `--no-gitignore` | Do not honor the project's `.gitignore`. |
| `-q, --quiet` | Suppress progress output. |
| `-V, --version` | Print version. |
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