architecture-knowledge-graph

name	architecture-knowledge-graph
description	Guide for reading a codebase and building a high-quality, persistent architecture knowledge graph via the Excalidraw Architect MCP kg_* tools. Use when creating or updating the knowledge graph (.claude/architecture.md), mapping services and their dependencies, or analyzing one or more repos to capture how services communicate.

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).
3. Linking pass — only after all services exist, add edges with kg_link. Linking before a target exists fails; that's why discovery comes first.
4. kg_lint — catch dangling references, cycles, and single points of failure. Fix them before rendering.
5. 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:

Signal in code	Link	Label / style
HTTP client, base URL, OpenAPI/Swagger spec	sync call	"REST /orders", style: solid
gRPC stub / proto service	sync call	"gRPC GetOrder", style: solid
Kafka/SQS/RabbitMQ producer	async event	"Kafka order.created", style: dashed
Kafka/SQS/RabbitMQ consumer	async event (incoming)	label with the same topic
DB connection string / ORM config	datastore	"reads/writes", style: solid
Service-discovery / env var (PAYMENTS_URL)	dependency	name the protocol

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.