arch-blueprint: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

arch-blueprint is a CLI that generates architecture diagrams (PlantUML or D2) from a Python project's module import graph. It is built on top of grimp, which constructs the import graph.

Commands

This project uses uv for environment and dependency management.

• Install/sync deps: uv sync (CI uses uv sync --locked)
• Run all checks (what CI runs): uv run pre-commit run -a (lint, format, mypy, pytest)
• Run the test suite only: uv run pytest
• Format: uv run ruff format
• Lint (with autofix): uv run ruff check --fix src tests
• Type-check (strict mypy): uv run mypy ./src ./tests
• Run the CLI against a project: uv run arch-blueprint <project_dir> -m '<pattern>' [-f puml|d2]
  • Example: uv run arch-blueprint src -m 'arch_blueprint.*'
  • Graphing this project is a special case: arch_blueprint is already in sys.modules (the CLI is it), so find_spec resolves to the running copy whatever <project_dir> says. To graph a different checkout, put it first on PYTHONPATH so that copy is the one running.
  • --modules/-m accepts grimp glob patterns (pkg.*, pkg.**, pkg.*.*.models.*).
  • -m can be repeated to graph several top-level packages at once and draw the links between them — useful when <project_dir> is a root with no __init__.py containing sibling packages (e.g. -m 'app1.*' -m 'app2.*'). A cross-package link is drawn only when both endpoints belong to the selected set — which includes a dependency on a package whose children were selected, since pkg.* never selects pkg itself.
  • --format/-f defaults to puml; --no-cycle-details hides per-module edges on cycles.
  • --metric NAME (repeatable) displays a metric. A node metric (fan_in, fan_out, instability) renders as a block on each node; a link metric (edge_weight) renders as a label on each connection, including cyclic ones (as forward/backward). An unknown name is an error, not a silent no-op.
• Runnable example fixture: uv run arch-blueprint examples/project_root -m 'app1.*' -m 'app2.*' -m 'plugins.**' (see examples/README.md) — exercises multi-root cross-links and namespace-package handling.