Architecture Knowledge Graph Guide

This skill teaches you how to turn a codebase into a clean, durable knowledge graph using the kg_* MCP tools. The graph (default .claude/architecture.md) is the single source of truth; diagrams are rendered views of it.

Graph quality depends almost entirely on how well you read the code. The MCP preserves, validates, and renders whatever you put in — it does not analyze the codebase. That analysis is your job.

Core Principle

Model services/components and how they communicate, not classes, functions, or every import. A "service" is a deployable unit / bounded context — one repo, one container, one logical responsibility.

Workflow (do the passes in order — don't interleave)

1. `kg_init` once (or kg_import to bootstrap from an existing .excalidraw).
2. Discovery pass — identify every service first. Add each with

kg_add_service, setting component_type, domain, and owner while the info is in front of you (Dockerfiles, CODEOWNERS, READMEs, manifests).

1. Linking pass — only after all services exist, add edges with kg_link.

Linking before a target exists fails; that's why discovery comes first.

1. `kg_lint` — catch dangling references, cycles, and single points of

failure. Fix them before rendering.

1. `kg_render` (whole graph) or **kg_render_view / kg_render_around /

kg_render_domain** for focused diagrams.

How to find the edges (where services talk)

Look for these signals and translate each into a labelled kg_link:

Cross-repo detection (multiple repos)

To connect services across repos, match a producer in repo A to a consumer in repo B using the shared join key:

• Async: topic / queue name (A publishes order.created, B subscribes

order.created → kg_link order-svc -> fulfilment-svc "Kafka order.created" style=dashed).

• Sync: the called service's route/host (A calls https://payments/charge

→ link A → payments).

Do a producer/consumer inventory across all repos before linking, so you don't miss an edge whose two ends live in different codebases.

Conventions (keep the graph consistent across sessions)

• Stable kebab-case ids, reused everywhere: order-service — never

OrderService one session and orders the next. Id drift silently corrupts a cumulative graph.

• Every edge is labelled with the mechanism. No bare arrows between services.
• Style encodes transport: solid = sync (REST/gRPC/DB), dashed =

async (events/queues). Consistency makes diagrams instantly readable.

• Set `domain` to group services (team / bounded context / tier) so you can

render one domain at a time.

Granularity

The full graph may be large, but any single rendered view should stay readable (~6–15 services). If a domain has 20 services, render it per sub-domain with kg_render_domain / kg_render_view rather than one giant picture. Resist decomposing a service into its internal classes — that's a different diagram.

Known limitation: parallel edges

A dependency is keyed on (from_id, to_id), so a second kg_link between the same pair replaces the first. If A talks to B two ways (REST and Kafka), combine them into one label — "REST /orders · Kafka order.created" — or link the primary transport. Don't issue two kg_link calls expecting two arrows.

Verify

Unlike diagrams, the graph is deterministically checkable. After building, run whats_connected_to <service> and kg_lint to sanity-check the topology matches your understanding of the system before sharing rendered views.