KG-ARCHMAP 0.8.0

Static architecture analysis and visualization for software projects.

ArchMAP

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

• Current release: v0.8.0
• Primary runtime: Python >=3.11
• Interactive UI: built-in static UI + Node dev server option
• Distribution: PyPI package + Windows executable

Installation

From PyPI

pip install archmap

For local development

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

Quick demo

Run the bundled sample project:

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

Useful API endpoints while serve is running:

• GET /api/graph
• GET /api/health
• GET /api/project
• POST /api/reanalyze

CLI overview

Analyze

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

Quality gates for CI:

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

Use analyze for the full report, quality gates, Mermaid, JSON, and Cytoscape exports.

Explain

archmap explain <path>

Prints a simple architecture summary for tired humans:

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, such as /auth, /payments, /users, 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

Git workflow (professional flow)

Branch promotion model:

feat/* -> dev -> release/* -> main

Also supported:

• feature/* (legacy alias)
• fix/*
• docs/*

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
• docs/BRANCHING.md

Repository layout

ArchMAP/
+-- .github/                  # CI/release workflows and PR template
+-- docs/                     # MkDocs documentation
+-- examples/                 # sample project for demos
+-- logs/                     # runtime/archive log organization
+-- 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
+-- NOTICE.md                 # original distribution notice
`-- README.md

Logs and artifacts

• Runtime logs: logs/runtime/ (git-ignored)
• Historical logs: logs/archive/
• Build artifacts: generated locally (build/, dist/) and should not be committed as source changes

Windows executable

Build locally:

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

This script:

• Builds dist/archmap.exe
• Creates a versioned binary copy
• Writes dist/archmap-build-info.json with SHA256
• Runs executable smoke test (archmap.exe version)

Node development server utilities

For frontend/API exploration with dynamic Python analysis:

npm run serve:web -- --path .

Original distributor rights

Original distributor and primary author: Kaua Gabriel / Kauã Gabriel (Kaua-KGzin).

Redistributions must preserve:

• LICENSE
• NOTICE.md

License

MIT. See LICENSE.