KG-ARCHMAP 0.9.0

Static architecture analysis and visualization for software projects.

Static architecture analysis for software repositories.

---

ArchMAP scans source code, builds dependency graphs, detects cycles, reports architectural risks, and serves an interactive web UI.

Supported languages: Python · JavaScript · TypeScript · Rust · Go · PHP · Java · C# · C/C++

Status

Release	v0.8.0
Runtime	Python >=3.11
UI	built-in static UI + Node dev server
Distribution	PyPI (KG-ARCHMAP) + Windows .exe

Installation

From PyPI

pip install KG-ARCHMAP

For local development

git clone https://github.com/Kaua-KGzin/ArchMAP
cd ArchMAP
python -m pip install -e ".[dev]"

Quick demo

archmap analyze examples/sample-project --format both --include-cytoscape
archmap serve examples/sample-project

Useful API endpoints while serve is running:

Endpoint	Description
GET /api/graph	Full dependency graph JSON
GET /api/health	Health score + grade
GET /api/project	Project metadata
POST /api/reanalyze	Trigger a fresh analysis

CLI overview

Analyze

archmap analyze <path> --format json|mermaid|both

Quality gates for CI:

archmap analyze . --fail-on-risks --top 10

Explain

archmap explain <path>

Prints a simple architecture summary:

auth -> users, payments
payments -> gateway

Risk

archmap risk <file> [path]

Shows blast radius, incoming/outgoing dependencies, and the file risk score.

Improve

archmap improve [path] --out-script .codeatlas/refactor.ps1

Suggests a cleaner project structure and can generate a helper refactor script.

Serve

archmap serve <path> --host 0.0.0.0 --port 3000

Diff

# Compare two git refs
archmap diff HEAD~5 HEAD

# Compare two saved JSON snapshots (no git required)
archmap diff --snapshot-a before.json --snapshot-b after.json

archmap history --repo . --limit 12

Trace

archmap trace src/main.py .
archmap trace src/main.py . --unreachable --max-depth 3

Shows every file reachable from an entrypoint through the dependency graph, grouped by depth, with coverage percentage.

Init (blueprint from real graph)

archmap init                       # scan directory names
archmap init --from-analysis       # derive layer rules from actual dependency graph
archmap init --from-analysis --dry-run

Advise (LLM architectural advisor)

archmap advise .                                          # Claude (ANTHROPIC_API_KEY)
archmap advise . --provider openai                        # OpenAI (OPENAI_API_KEY)
archmap advise . --provider ollama                        # local Ollama
archmap advise . --provider custom --base-url http://localhost:1234  # any OpenAI-compat API

VS Code Extension

The bundled VS Code extension provides zero-config IDE integration:

• Inline diagnostics (cycles, layer violations, god modules) in the Problems panel
• Status bar health score + grade
• ArchMAP: Analyze Project command
• ArchMAP: Open Web UI command
• ArchMAP: Trace File Reachability webview
• archmap.analyzeOnSave for CI-style continuous feedback

Git workflow

Branch promotion model: feat/* → dev → release/* → main

Rules:

1. No direct feature merge into main.
2. release/* accepts only stabilization changes.
3. CI must pass before merge.
4. Update docs/changelog when behavior changes.

See CONTRIBUTING.md and docs/BRANCHING.md.

Repository layout

ArchMAP/
├── .github/          # CI/release workflows and PR template
├── docs/             # MkDocs documentation + assets
├── examples/         # sample project for demos
├── logs/             # runtime/archive log organization
├── resources/        # brand assets (logos, icons)
├── scripts/          # automation helpers (smoke, benchmark, exe build)
├── src/archmap/      # Python source code
├── tests/            # automated test suite
├── vscode-extension/ # VS Code extension (inline diagnostics, trace view)
├── web-ui/           # Node dev server + static assets
├── archmap.spec      # PyInstaller spec
└── README.md

Logs and artifacts

• Runtime logs: logs/runtime/ (git-ignored)
• Historical logs: logs/archive/
• Build artifacts: generated locally (build/, dist/) — not committed

Windows executable

powershell -ExecutionPolicy Bypass -File scripts/build-exe.ps1 -Clean

Builds dist/archmap.exe, creates a versioned binary copy, writes dist/archmap-build-info.json with SHA256, and runs a smoke test.

Node development server

npm run serve:web -- --path .

License

MIT — see LICENSE.

Original distributor and primary author: Kaua Gabriel / Kauã Gabriel (Kaua-KGzin).
Redistributions must preserve LICENSE and NOTICE.md.