Metadata-Version: 2.5
Name: excalidraw-architect-mcp
Version: 2.0.0
Summary: An MCP server that generates beautiful Excalidraw architecture diagrams with perfect auto-layout, stateful editing, and architecture-aware component styling.
Project-URL: Homepage, https://github.com/BV-Venky/excalidraw-architect-mcp
Project-URL: Repository, https://github.com/BV-Venky/excalidraw-architect-mcp
Project-URL: Issues, https://github.com/BV-Venky/excalidraw-architect-mcp/issues
Author: Bhukya Venkatesh
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,diagram,excalidraw,mcp,mermaid
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0
Requires-Dist: grandalf>=0.8
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: png
Requires-Dist: cairosvg>=2.7; extra == 'png'
Description-Content-Type: text/markdown

# Excalidraw Architect MCP
<!-- mcp-name: io.github.BV-Venky/excalidraw-architect-mcp -->
[![PyPI](https://img.shields.io/pypi/v/excalidraw-architect-mcp)](https://pypi.org/project/excalidraw-architect-mcp/)
[![Cursor Directory](https://img.shields.io/badge/Cursor-Directory-purple)](https://cursor.directory/mcp/excalidraw-architect-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/excalidraw-architect-mcp?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/excalidraw-architect-mcp)


**Every diagram your engineering docs need — as hand-drawn Excalidraw, generated by your AI.**

Twenty-five diagram types. Architecture and flowcharts, but also sequence diagrams, state machines, ER models, swimlanes, timelines, Gantt charts, quadrants, funnels, and hand-sketched bar/line/scatter charts. No coordinates to hallucinate, no Figma, no stale PNGs.

## The Problem

When you're onboarding onto a codebase, designing a new system, or documenting how something works, a diagram communicates in seconds what pages of text can't. But the options aren't great.

Mermaid is quick to generate and locked down — you can't drag a node, group things visually, or annotate it afterwards. Figma means thirty minutes of manual work per picture. And when an LLM writes Excalidraw JSON directly it hallucinates coordinates: boxes overlap, arrows tangle, and you fix it by hand.

Worse, most tools only cover *one* diagram type well. The moment your doc needs a sequence diagram next to the architecture sketch, you're switching tools and the two look nothing alike.

## The Solution

**excalidraw-architect-mcp** separates the *what* from the *where* — the AI describes structure, the engine does the pixel math.

Your LLM says what the components, actors, tiers, or data points are. The MCP picks the layout algorithm for that diagram type, styles it, and writes a real `.excalidraw` file you can open and keep editing. 50+ technologies (Kafka, PostgreSQL, Redis…) get auto-styled, every diagram can be revised in natural language, and it runs fully offline in Cursor/Claude Code/Windsurf — no API keys.

- **25 diagram types, one grammar** — [see them all](#-25-diagram-types), from architecture to Gantt to scatter plots
- **Genuinely hand-drawn output** — a pure-Python port of the roughjs stroke generator, so exported SVG/PNG looks like the Excalidraw canvas, not a clean-geometry approximation
- **Perfect layouts every time** — Sugiyama with adaptive spacing for graphs; purpose-built geometry for everything else
- **Architecture-aware styling** — say "Kafka" and get a stream-styled node, not a generic rectangle
- **Talk to your diagrams** — add, remove, or rewire any diagram in natural language; the spec lives in the file
- **Export to SVG & PNG** — no browser, no Node.js
- **Living architecture knowledge graph** — optionally persist your system as a version-controlled model the AI can query and lint ([details](#-architecture-knowledge-graph))

## 📐 25 Diagram Types

> Every image below is a real `.excalidraw` file generated by this MCP — zero manual positioning. Click any one to see it full size.

<table>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/architecture.png"><img src="showcase/gallery/architecture.png" alt="Architecture diagram"></a><br><b>Architecture</b><br><sub>Components + connections</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/dp_integration.png"><img src="showcase/gallery/dp_integration.png" alt="DP integration diagram"></a><br><b>DP integration</b><br><sub>Sources → core → consumers</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/sequence.png"><img src="showcase/gallery/sequence.png" alt="Sequence diagram"></a><br><b>Sequence</b><br><sub>Messages over time</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/timeline.png"><img src="showcase/gallery/timeline.png" alt="Timeline diagram"></a><br><b>Timeline</b><br><sub>Events on an axis</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/gantt.png"><img src="showcase/gallery/gantt.png" alt="Gantt diagram"></a><br><b>Gantt</b><br><sub>Tasks and phases</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/quadrant.png"><img src="showcase/gallery/quadrant.png" alt="Quadrant diagram"></a><br><b>Quadrant</b><br><sub>Two-axis positioning</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/pyramid.png"><img src="showcase/gallery/pyramid.png" alt="Pyramid / funnel diagram"></a><br><b>Pyramid / funnel</b><br><sub>Ranked tiers or drop-off</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/venn.png"><img src="showcase/gallery/venn.png" alt="Venn diagram"></a><br><b>Venn</b><br><sub>Set overlap</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/loop.png"><img src="showcase/gallery/loop.png" alt="Loop diagram"></a><br><b>Loop</b><br><sub>Flywheel around a hub</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/bar.png"><img src="showcase/gallery/bar.png" alt="Bar chart diagram"></a><br><b>Bar chart</b><br><sub>Categorical comparison</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/line.png"><img src="showcase/gallery/line.png" alt="Line chart diagram"></a><br><b>Line chart</b><br><sub>Trends over time</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/scatter.png"><img src="showcase/gallery/scatter.png" alt="Scatter plot diagram"></a><br><b>Scatter plot</b><br><sub>Distribution + correlation</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/nested.png"><img src="showcase/gallery/nested.png" alt="Nested diagram"></a><br><b>Nested</b><br><sub>Hierarchy by containment</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/layers.png"><img src="showcase/gallery/layers.png" alt="Layer stack diagram"></a><br><b>Layer stack</b><br><sub>Stacked abstractions</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/medallion.png"><img src="showcase/gallery/medallion.png" alt="Medallion diagram"></a><br><b>Medallion</b><br><sub>Data quality tiers</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/er.png"><img src="showcase/gallery/er.png" alt="ER / data model diagram"></a><br><b>ER / data model</b><br><sub>Entities + fields</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/high_level.png"><img src="showcase/gallery/high_level.png" alt="High-level diagram"></a><br><b>High-level</b><br><sub>Stack inside a boundary</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/it_state.png"><img src="showcase/gallery/it_state.png" alt="IT current-state diagram"></a><br><b>IT current-state</b><br><sub>Legacy landscape</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/swimlane.png"><img src="showcase/gallery/swimlane.png" alt="Swimlane diagram"></a><br><b>Swimlane</b><br><sub>Cross-functional flow</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/process.png"><img src="showcase/gallery/process.png" alt="Process diagram"></a><br><b>Process</b><br><sub>Multi-actor workflow</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/data_flow.png"><img src="showcase/gallery/data_flow.png" alt="Data flow diagram"></a><br><b>Data flow</b><br><sub>Role-scoped pipeline</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/flowchart.png"><img src="showcase/gallery/flowchart.png" alt="Flowchart diagram"></a><br><b>Flowchart</b><br><sub>Decision logic with branches</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/tree.png"><img src="showcase/gallery/tree.png" alt="Tree diagram"></a><br><b>Tree</b><br><sub>Parent → children</sub></td>
  <td align="center" width="33%"><a href="showcase/gallery/org_chart.png"><img src="showcase/gallery/org_chart.png" alt="Org chart diagram"></a><br><b>Org chart</b><br><sub>Ownership + escalation</sub></td>
</tr>
<tr>
  <td align="center" width="33%"><a href="showcase/gallery/state.png"><img src="showcase/gallery/state.png" alt="State machine diagram"></a><br><b>State machine</b><br><sub>States + transitions</sub></td>
  <td width="33%"></td>
  <td width="33%"></td>
</tr>
</table>

### Choosing and calling

The gallery above is ordered by how often you'll reach for each type. Internally they fall into five families, which is what decides the layout engine:

| Family | Types |
|---|---|
| **Graph** | `architecture` · `flowchart` |
| **Structural** | `tree` · `org_chart` · `state` · `nested` · `layers` · `medallion` · `er` · `high_level` · `it_state` |
| **Flow** | `swimlane` · `process` · `data_flow` · `dp_integration` · `sequence` |
| **Geometric** | `timeline` · `quadrant` · `pyramid` (+ funnel) · `venn` · `loop` · `gantt` |
| **Charts** | `bar` · `line` · `scatter` |

`architecture` and `flowchart` are graphs and take `nodes` + `connections`. Every other type takes a `diagram_type` and a `spec` shaped for it:

```python
create_diagram(
    output_path="./checkout.excalidraw",
    diagram_type="sequence",
    spec={
        "title": "Checkout authorization",
        "actors": [{"id": "web", "label": "Web app"}, {"id": "psp", "label": "Payment PSP"}],
        "messages": [
            {"from_id": "web", "to_id": "psp", "label": "authorize"},
            {"from_id": "psp", "to_id": "web", "label": "approved",
             "kind": "return", "focal": True},
        ],
    },
)
```

Call `list_diagram_types()` for when-to-use guidance on each, and `get_diagram_schema("<type>")` for the exact spec shape. Or just ask: *"draw the PR review flow as a swimlane"*.

**Two conventions worth knowing.** Mark one or two elements `"focal": true` — that earns the accent color, and marking five spends the signal. And chrome (axes, gridlines, lane dividers) deliberately renders crisp while shapes and data marks render hand-drawn; that contrast is what keeps a sketchy chart legible instead of noisy.

**Editing works on every type.** The validated spec is stored inside the `.excalidraw` file, so you patch it rather than rebuild it:

```python
modify_diagram(path, [{"op": "update_spec", "patch": {"title": "Revised plan"}}])
```

Lists are replaced wholesale — to change one tier, send the whole `tiers` list.

Regenerate every image above with `python scripts/generate_showcase.py --png`.
## See It In Action

> Every frame below is generated entirely by AI using this MCP - zero manual positioning.

### E-Commerce Platform Architecture

![E-Commerce Platform Demo](showcase/demo_ecommerce.gif)

### Payment Processing Flow

![Payment Processing Flow Demo](showcase/demo_payment.gif)

## Use Cases

- **Onboarding onto a new codebase** — point it at a service and get a high-level architecture diagram without reading a line of code, then a sequence diagram for the one flow that matters.
- **Design docs and RFCs** — an architecture sketch, a state machine for the new lifecycle, a quadrant for the options you rejected, and a Gantt for the rollout. One tool, one visual language.
- **Runbooks and incident write-ups** — sequence diagrams for what happened, timelines for when, swimlanes for who did what.
- **Data platform documentation** — medallion tiers, role-scoped pipelines, integration topology.
- **Reporting without a BI tool** — hand-drawn bar/line/scatter charts that sit next to your architecture diagram instead of clashing with it.
- **Documentation that stays alive** — commit the `.excalidraw` file and revise it in natural language as the system changes. No more stale diagrams from six sprints ago.

## Quick Start

### Install

```bash
pip install excalidraw-architect-mcp
```

For **PNG export** support (SVG works out of the box):

```bash
pip install excalidraw-architect-mcp[png]
```

Or run without installing (requires [uv](https://docs.astral.sh/uv/)):

```bash
uvx excalidraw-architect-mcp
```

### Configure MCP in Your IDE

**Cursor** - Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "excalidraw-architect": {
      "command": "excalidraw-architect-mcp",
      "transport": "stdio"
    }
  }
}
```

**Claude Code** - Run this one-liner:

```bash
claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope user
```

Or add manually to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "excalidraw-architect": {
      "type": "stdio",
      "command": "excalidraw-architect-mcp"
    }
  }
}
```

**Windsurf / Other IDEs** - Same pattern; point to the `excalidraw-architect-mcp` command over stdio.

### Install the Excalidraw Architect Skill (recommended for the 25 types)

[`skills/excalidraw-architect/`](skills/excalidraw-architect/SKILL.md) teaches the AI **which** of the 25 types to pick and how much to put in one — the selection table, the density budget, the reserved-accent rule, and a worked example of every spec.

```bash
ln -s "$PWD/skills/excalidraw-architect" ~/.claude/skills/excalidraw-architect
```

The same guidance also ships inside the server via `list_diagram_types()` and `get_diagram_schema()`, so Cursor, Windsurf, and Zed get it without installing anything — the skill just puts it in context up front instead of one call later. Both are generated from a single source (`src/excalidraw_mcp/diagrams/registry.py`); a test fails the build if they drift.

### Install the Diagram Design Skill (recommended)

This repo includes a [Diagram Design Skill](.skills/excalidraw-diagram-design/SKILL.md) that teaches the AI how to structure diagrams for the best results - node count limits, topology rules, edge label guidelines, and common patterns.

**For Cursor users:**

```bash
mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \
curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md
```

**For other IDEs:** Download the [SKILL.md](.skills/excalidraw-diagram-design/SKILL.md) file and add it to your IDE's prompt context or system instructions.

The AI will automatically pick up the skill and apply it when generating diagrams. Feel free to modify the rules to suit your preferences - tweak node limits, add your own patterns, or adjust styling guidelines.

### Install the Knowledge Graph Skill (recommended for the graph workflow)

For the [architecture knowledge graph](#-architecture-knowledge-graph), this repo also includes an [Architecture Knowledge Graph Skill](.skills/architecture-knowledge-graph/SKILL.md). It teaches the AI how to read a codebase well — identify service boundaries, map communication signals (HTTP / gRPC / Kafka / DB) to the right labelled links, match producers and consumers across repos, and keep the graph clean (stable ids, every edge labelled, lint before render).

**For Cursor users:**

```bash
mkdir -p ~/.cursor/skills/architecture-knowledge-graph && \
curl -o ~/.cursor/skills/architecture-knowledge-graph/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/architecture-knowledge-graph/SKILL.md
```

**For other IDEs:** Download the [SKILL.md](.skills/architecture-knowledge-graph/SKILL.md) file and add it to your IDE's prompt context or system instructions.

> **A note on diagram complexity:** As the number of components and connections grows, diagrams inevitably become harder to read - this is true for humans drawing by hand too, not just automated layout. For best results, aim for **6-15 nodes** in architecture diagrams and **10-25 nodes** in detailed flows. If your system is larger, split it into multiple focused diagrams rather than cramming everything into one.

### Use It

Just ask your AI IDE naturally:

> "Create a high-level architecture diagram of this codebase"

> "Create an architecture diagram for a microservices system with an API Gateway, Auth Service, User Service, Order Service, PostgreSQL, Redis cache, and Kafka event bus"

> "Convert this mermaid diagram to excalidraw diagram"

> "Add a Caching layer to the Order Service in the High Level architecture diagram"

> "Export the architecture diagram to SVG"

> "Export the diagram as a PNG at 3x resolution"

The AI calls the MCP tool with the relationship map. The MCP handles layout, styling, and output. Open the resulting `.excalidraw` file with the [Excalidraw VS Code extension](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) or drag it into [excalidraw.com](https://excalidraw.com).

## Features

### Auto Layout Engine

Uses the Sugiyama hierarchical layout algorithm with:

- **Adaptive layer gaps** - spacing adjusts based on edge label length
- **Hub node stretching** - gateways/load balancers stretch to span connected services
- **Obstacle-aware edge routing** - arrows curve around intermediate nodes instead of cutting through them
- **Disconnected component stacking** - separate subgraphs (e.g., monitoring stack) are placed without overlap

### Component Library

50+ technology mappings with automatic visual styling:

| Category | Technologies |
|---|---|
| Database | PostgreSQL, MySQL, MongoDB, DynamoDB, Cassandra, ClickHouse, SQLite, CockroachDB |
| Message Queue | Kafka, RabbitMQ, SQS, Redis Streams, NATS |
| Cache | Redis, Memcached, Varnish |
| Load Balancer | Nginx, HAProxy, ALB/ELB, Traefik, Envoy |
| Compute | Docker, Kubernetes, Lambda, ECS, Fargate |
| Storage | S3, GCS, Azure Blob, MinIO |
| API | REST, GraphQL, gRPC, WebSocket |
| CDN | CloudFront, Cloudflare |
| Monitoring | Prometheus, Grafana, Datadog, ELK |
| Client | Browser, Mobile, Desktop, CLI |

### Stateful Editing

Diagram metadata is embedded in the `.excalidraw` file. Ask the AI:

> "Add a Redis cache in front of the database in the existing diagram"

The MCP reads the current state, applies the modification, and re-renders with proper layout.

### Mermaid Conversion

Already have a Mermaid flowchart? Convert it:

> "Convert this Mermaid diagram to Excalidraw" (paste your Mermaid syntax)

### Image Export That Still Looks Hand-Drawn

Excalidraw's sketchy look is not stored in the file — it is produced at render time by [roughjs](https://roughjs.com), which redraws every shape as two jittered strokes seeded from the element. An exporter that emits a plain `<rect>` reproduces the geometry perfectly and the character not at all.

So this one ports the roughjs stroke generator to Python: same seeded PRNG, same line/curve/ellipse/fill routines. Exports match the canvas — doubled pencil strokes, overshooting circles, V-shaped arrowheads, and fills that sit slightly inside their outlines.

- **SVG** — zero extra dependencies, no browser, no Node.js
- **PNG** — requires the optional `cairosvg` package (`pip install excalidraw-architect-mcp[png]`); configurable resolution multiplier (default 2×)

Chrome renders crisp on purpose. Axes, gridlines, and lane dividers are drawn at `roughness: 0`, because a 1px hairline with hand-drawn jitter is indistinguishable from noise.

**Fonts.** Excalidraw's `Excalifont` is a bundled webfont, so a standalone SVG has nothing to resolve it to. Exports name a stack of real handwriting faces (Excalifont → Virgil → Segoe Print → Bradley Hand → Chalkboard) instead of the generic CSS `cursive`, which on macOS resolves to the calligraphic Apple Chancery. For output that looks identical everywhere, pass a font file to embed it:

```python
export_to_svg("arch.excalidraw", "arch.svg", embed_font="Excalifont.woff2")
```

> "Export the architecture diagram as an SVG"

## MCP Tools

### Diagram tools

| Tool | Description |
|---|---|
| `create_diagram` | Create a diagram of any of the 25 supported types |
| `list_diagram_types` | Every type with when-to-use / when-not-to guidance |
| `get_diagram_schema` | Spec schema + worked example for one type |
| `mermaid_to_excalidraw` | Convert Mermaid flowchart syntax to `.excalidraw` |
| `modify_diagram` | Patch an existing diagram — nodes/connections, or the stored spec |
| `get_diagram_info` | Read current diagram state (call before modifying) |
| `export_diagram` | Export `.excalidraw` to SVG or PNG image |

### Knowledge graph tools (`kg_*`)

Optional. For the architecture-documentation workflow only — the knowledge graph (default `.claude/architecture.md`) becomes the source of truth and diagrams become rendered views of it. See [Architecture Knowledge Graph](#-architecture-knowledge-graph) below.

| Tool | Description |
|---|---|
| `kg_init` | Create a new knowledge graph file |
| `kg_add_service` / `kg_remove_service` | Add/update or remove a service (with type, domain, owner, tags, links) |
| `kg_link` / `kg_unlink` | Add/remove a dependency (parallel edges supported — e.g. REST *and* Kafka between the same pair) |
| `kg_set_domain` | Group a service into a domain / bounded context |
| `kg_info` | Summarize services, domains, and topology |
| `kg_render` | Render the whole architecture to `.excalidraw` |
| `kg_render_view` | Render a focused diagram of specific services |
| `kg_render_around` | Render everything within N hops of a service |
| `kg_render_domain` | Render a single domain |
| `kg_import` | Bootstrap the graph from an existing `.excalidraw` diagram |
| `whats_connected_to` | Impact analysis — upstream/downstream blast radius |
| `kg_path` | Trace the dependency path between two services |
| `kg_lint` | Health check: cycles, single points of failure, orphans, dangling refs |
| `kg_export` | Export the graph to Mermaid, Graphviz DOT, or JSON |
| `kg_diff` | Show how the architecture changed since a git ref |
| `kg_onboarding_doc` | Generate a human onboarding guide from the graph |
| `kg_drift` | Detect drift between the declared graph and Python imports |

## 🧠 Architecture Knowledge Graph

> **Optional, and only for architecture.** Everything above works without it. But if you document one system repeatedly, a one-off diagram goes stale the moment you close it — so architecture diagrams can instead be *views* of a persistent, version-controlled model the AI builds once and reuses everywhere.

![Knowledge Graph rendered diagram](showcase/knowledge_graph.svg)

> *The diagram above was rendered from a knowledge graph — a single `.claude/architecture.md` file. Notice `Order Service → Payment Service` appears twice: a solid `REST /charge` call and a dashed `Kafka payment.requested` event. Two communication modes, two arrows.*

### Why a knowledge graph?

A one-off diagram goes stale the moment you close it. A **knowledge graph** is a living model:

- **One source of truth, many views** — store the whole system once, then render the full picture, a single domain, or everything within N hops of one service.
- **Consistent across diagrams** — the same service keeps the same id, styling, and metadata everywhere.
- **Queryable** — ask "what breaks if payments goes down?" and get the real blast radius, not a guess.
- **Self-checking** — lint for dependency cycles, single points of failure, and orphaned services.
- **Lives in git** — review architecture changes in PRs; the markdown diffs cleanly.

### The file is human- *and* machine-readable

The graph is a single markdown file (default `.claude/architecture.md`):

```markdown
## Services
- order-service: Order Service [type: service] [domain: orders] [owner: @orders]
- payment-service: Payment Service [type: service] [domain: payments] [owner: @payments]

## Dependencies
- order-service -> payment-service : "REST /charge"
- order-service -> payment-service : "Kafka payment.requested" [style: dashed]
```

Edit it by hand or let the AI maintain it — it round-trips losslessly either way.

### Just ask your AI

> "Map this codebase into the architecture knowledge graph"

> "Link the order service to payments over Kafka"

> "What depends on the payment service? Render just its neighborhood"

> "Render the orders domain as a focused diagram"

> "Lint the architecture for cycles and single points of failure"

> "Import my existing diagram.excalidraw into the knowledge graph"

> "Generate an onboarding guide from the architecture"

See the [Knowledge Graph tools](#mcp-tools) for the full tool list.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT - see [LICENSE](LICENSE).
