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 draw <project_dir> [-m '<pattern>'] [-f FMT] [-o FILE]
  • Example: uv run arch-blueprint draw src -m 'arch_blueprint.*'
  • Every command is explicit (draw, diff, history, serve). The old implicit form arch-blueprint <dir> -m ... and the old render SNAPSHOT are gone; each gets an exit-2 hint naming the draw command to run instead. draw takes a project directory or a snapshot file (an existing file, or any *.json).
  • Without -m, draw and diff --base draw every package in <project_dir> whole (extract/layout.py:detect_roots → pkg.**, noted on stderr); history without ROOTs does the same at --head. A src-layout root (src/ a namespace dir holding packages) is refused with a hint rather than drawn as src.myapp.
  • -o FILE writes to a file; without -f its extension picks the format (.puml, .d2, .json, .png → puml-png). -f puml-png / d2-png draw an image through the IMAGE_RENDERERS tool and require -o.
  • 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. The notes listing a cycle's imports are opt-in in every command (--cycle-details), for a pair and a longer cycle alike. diff and history draw the diff over the whole graph; --changes-only draws just the changes and the modules they touch.
  • --links namespace|module (default namespace) chooses what an arrow connects: the namespaces where two modules' paths diverge, or the nodes themselves. Accepted by every command that builds a graph (draw PROJECT_DIR, diff --base, history), not by draw SNAPSHOT or a snapshot-file diff (_reject_links) — a snapshot records the level it was built at. Even an explicit --links namespace is rejected there (the parser default is None, resolved by _link_level), and a diff of two snapshots of different levels is exit 2. A level also says how it is drawn (Level.nested → RendererOptions.nested), laid out by renderer/layout.py (see Frames and labels below): namespace and the -grouped levels are nested — every dotted prefix a frame, a chain of frames that hold nothing but one frame merged into one labelled by the joined path (app.features.core.executory_processes). module and class are flat — every node one box labelled by its dotted name less the prefix all drawn names share, which is shown once as the diagram title; every endpoint no node carries (a facade an arrow ends on) is declared as a node of its own. Containers only lengthen node-to-node arrows.
  • --links class|class-grouped make the nodes definitions, not modules: the top-level classes and module-level functions of every selected module, always together — a class that calls a function using another class depends on it through that function, drawn as two arrows. Arrows are always definition to definition, wherever a definition's code names another — bases, metaclass, decorators, class-level annotations, __init__, signatures, defaults and bodies (string annotations included). class is flat; class-grouped is nested (Level.nested), so every node sits in its module's frame. One edge per definition pair, so edge_weight is always 1 there. -m 'pkg.**' also takes the definitions of pkg/__init__.py (GrimpSource.pattern_stems). These levels parse every module's source with libcst — about ten times slower than the module levels. Example: uv run arch-blueprint draw tests/fixtures/classes -m 'refs.**' --links class-grouped.
  • --deps out|in (extract/focus.py:DEPS_DIRECTIONS, routed by follows_out / follows_in) makes -m the focus and also draws every object the focus directly depends on (out) or that directly depends on it (in), wherever in <project_dir> it lives, as a neighbor (BlueprintGraph.neighbors): muted and dashed (NEIGHBOR_COLOR, _format_neighbor), no metric blocks, labelled by its full name when flat (the flat prefix is the focus's; a facade endpoint no focused node lies under is a neighbor too — Layout.neighbors). The direction only picks the neighbors: every edge between the focus and a neighbor is drawn, either way, so a cycle through one is never half hidden; a neighbor's imports / references of anything but the focus are never read (no neighbor → neighbor edge), and stdlib / third-party code is never a node. Accepted where --links is (_reject_deps on snapshots); --metric with it is exit 2 (_check_deps, also for a snapshot built with it) — a neighbor's own imports are not read, so its numbers would lie; a --deps snapshot / history cache entry computes only the compute-only metrics (_undrawn_metrics). Example: uv run arch-blueprint draw tests/fixtures/focus_deps -m 'app.features.core.executory_processes.**' --deps out --links class.
  • --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. diff and history take it too: a changed value reads old → new (±d).
• Snapshot / draw a snapshot / diff (see Snapshot and diff below):
  • uv run arch-blueprint draw <project_dir> -m '<pattern>' -o graph.json — graph snapshot.
  • uv run arch-blueprint draw graph.json [-f FMT] [-o FILE] [--metric NAME] — draw a snapshot.
  • uv run arch-blueprint diff OLD.json NEW.json [-f FMT] [-o FILE] [--metric NAME] — draw what changed.
  • uv run arch-blueprint diff --base REV [--head REV] <project_dir> [-m '<pattern>'] — both sides built from git (--head defaults to the working tree).
  • uv run arch-blueprint history <project_dir> [ROOT ...] [-m '<pattern>'] [--base REV] [--head REV] [-o DIR] [-f puml|d2|puml-png|d2-png] — an album: a diagram and a diff per commit that changed the graph (see History album below).
• Interactive viewer (see Viewer below): uv run arch-blueprint serve <project_dir> [-m '<pattern>'] [--links module|class] [--port N] [--no-open] — a local page (127.0.0.1) to fold / unfold packages, focus a node, list an arrow's imports; the view state lives in the URL.
• Runnable example fixture: uv run arch-blueprint draw examples/project_root -m 'app1.*' -m 'app2.*' -m 'plugins.**' (see examples/README.md) — exercises multi-root cross-links and namespace-package handling.