In short:
ak-diagramturns your system description into typed JSON IR, then compiles it offline into an interactive HTML reader, an SVG file or an HTML fragment to embed. For hand sketches it points you toak-excalidraw, for static images to publish toak-tech-graph, for Mermaid inside markdown toak-mermaidjs-v11. It does not let you place coordinates or drag nodes.
Disclosure: I maintain AgentKit and have an affiliate relationship with it: the AgentKit link in this post is an affiliate link; buying through it gets you 30% off.
Summary
Use it when you need an architecture map, a workflow, an API call order, a data pipeline or a state lifecycle that teammates can open, that goes into docs or a presentation, and that you can update by editing the IR and compiling again. You do not need it for a hand sketch, a static image to print or publish, or a Mermaid block that lives inside markdown.
flowchart LR
A["System description or IR file"] --> B["ak-diagram"]
B --> C["HTML reader, SVG or fragment"]
C --> D["Stop: you open, embed or send the file"]
A -.->|"Hand sketch"| E["ak-excalidraw"]
A -.->|"Static image to publish"| F["ak-tech-graph"]
A -.->|"Mermaid in docs"| G["ak-mermaidjs-v11"]Four things to know:
| Concept | Question | Example |
|---|---|---|
| Diagram type | Which of the 5 types is the thing you want to draw? | Gateway, auth, database is architecture. A release approval is workflow. API call order is sequence. An ETL pipeline is dataflow. Order states are lifecycle. |
| Typed JSON IR | What do you declare, and what does the machine handle? | You declare gw with role gateway at layer 0, auth at layer 1, db at layer 2, plus two edges. The compiler splits the columns and reduces crossings. |
| Output | Where will the diagram live? | Sending it to a teammate to open in a browser: HTML. Putting it in docs or slides: SVG. Placing it in an existing HTML page: fragment. |
| Interactive reader | What can someone viewing the HTML file do? | / finds a node, clicking a node dims the rest, R shows the shortest path, L filters by role, F presents, [ ] move between chapters, M replays the animation. |
A trade-off to know: Mermaid .mmd files are drawn offline by the bundled Pele renderer, so they look different from stock Mermaid output. Only when Pele cannot read the diagram, or the machine has no node, does the output page load Mermaid from a CDN and need a network.
Sample prompt (architecture map):
/ak-diagram Draw the architecture of <app name>: a web client calls the API gateway,
the gateway calls the auth service and the order service, the order service writes to PostgreSQL
and pushes events to a queue for a worker that sends email. Everything sits in one VPC,
except the email provider outside it. Output an HTML file.| Flag | What it is for | Since ak |
|---|---|---|
--format | Picks the output type: html, svg or fragment | 2.15.0 |
--preset | Picks the style: classic, signal-flow, blueprint, editorial | 2.15.0 |
--theme | Light or dark background | 2.15.0 |
--out | Output file path | 2.13.0 |
Below is the detailed version: the run flow, 6 situations with prompts, each flag explained, the change history by ak release, and common pitfalls. The detailed version and the interactive page are for subscribers. Your agent can also search them through the portal's MCP.
Opens when your account has subscriber access
This guide is for subscribers
Once your account has access, the full piece, the interactive visual and the agent call all open.
- Sign in or create a modernEngineer accountReading access belongs to your account email.
- Choose a plan on the pricing page1, 3 or 12 months, paid by VietQR bank transfer. Access opens about a minute after the money arrives.
- Or redeem a Facebook subscriber codePeople supporting the page on Facebook get an activation code by message each month.
Already a subscriber? Sign in to read.
Use this piece in your agent
Get an API keyCopy the text below and paste it into Claude Code, Codex or whichever agent you use. The agent reads the piece and checks it against the repo you have open.
Read "ak-diagram: interactive system diagrams, laid out for you" on modernEngineer and apply it to this repo.
1. Call the content_get tool of the modernengineer MCP server with locale "en", slug "ak-diagram". If the modernengineer MCP server is not connected, stop and walk me through connecting it from https://modernengineer.dev/en/mcp.
2. Summarize the main steps of the piece and point out which apply to this repo.
3. Propose concrete changes and ask me before editing any file.Connect MCP in Claude Code (once)
claude mcp add --transport http modernengineer \
https://api.modernengineer.dev/mcp \
--header "Authorization: Bearer <API key>"Reading the full piece over MCP needs an API key from a subscriber account or one that bought this guide. Without access, the agent only gets the opening.
- Version
- v1.0.0
- Updated
- 22/10/2026
- Licence
- All rights reserved
- Slug
- ak-diagram
