Say what the relationship is
A call is not an event. A gateway is not a database. Different kinds and edge operators keep both the diagram and the PR review accurate about the system.
checkout => events "OrderPlaced"
Beautiful, interactive diagrams from text.
Describe the system in a readable .kdiagram file. Kekonic Diagrams measures the labels, places the nodes, and routes the connections. The same source becomes a portable SVG, a live embed, or an animated story.
$
npx @kekonic/diagrams-cli studioMeaning, not coordinates
A .kdiagram file is a system model: kinds, groups, and whether a link is a call or an event. It does not store x/y. Structural edits stay cheap. A pull request can show that an interaction became an event, while CI renders the SVG for readers who only need the picture.
billing: service "Billing"- billing -> events "Payment"+ billing => events "PaymentCaptured"Diagram-as-code does not have to look generic
Most text-to-diagram tools stop at a graph. Kekonic Diagrams sizes nodes to their labels, routes orthogonal edges with crossing treatment, places icons from the vocabulary, and themes the diagram as one system. The default holds up in a design review as well as a README.
- Software kinds readers already recognize: clients, gateways, services, brokers, stores
- Brand and theme-aware icons in the node vocabulary
- Custom themes when your destination needs its own paper and ink
A language for software structure
The vocabulary covers architecture, events, workflows, ERDs, sequences, and state machines. You supply the meaning. Layout and animation follow from that model.
Boundaries that layout can use
Groups are not decorative frames drawn after the fact. They participate in placement (stacks, grids, spans, density), so ownership and trust show up as structure.
arrange: grid · rowSpan: 2Walk one path through a dense graph
When the picture has many routes, animation tells one story. Trace a request or pulse a node. Author it over the same nodes and edges readers already have.
flow api -> checkout for 1.2sAsk an agent without inventing topology
“Draw our architecture” often invents services to finish the picture. The official skill inspects the code you point at, writes .kdiagram source, and runs the CLI. Missing facts stay in the notes. They do not become extra boxes.
Show a new engineer how checkout moves from the web app through payment authorization. Read the code. Do not invent services.
Found in the repo
Web app → API → Checkout → Billing → Stripe
Reported as an assumption
Mobile uses the same gateway — noted, not drawn as fact.
Checked
kdiagrams check · render · analyze
Grounded in the repo
Nodes come from what the agent found, or from an assumption it reports. It does not invent a queue to make the graph look complete.
Checked before it returns
kdiagrams check, render, and analyze run against the file. You get diagnostics. The source has to parse.
Reviewed like code
The source is ordinary text. Drop an invented box in a pull request the same way you drop an invented API.
$
Install and workflow →npx skills add kekonic/diagramsOne source. Pick the destination.
Author once. Deliver as a portable image, a Markdown fence, a live embed, or a CI artifact, without rewriting the model for each host.
README · wiki · static siteSelf-contained SVG
Theme values snapshotted in. No Kekonic runtime where it is displayed.
Any browser frameworkWeb componentPan, zoom, theme, and playback when readers need to explore the graph.
React applicationsLive view and playgroundInteractive view, or an editable source panel when teaching is the point.
Astro · MDX · VitePressMarkdown fencesBuild-time SVG from ```kdiagram blocks. Readers get an image.
Import SVG, data URL, source, React, or a custom element. Pick the query explicitly.
Pull requests · CICheck and renderValidate source, render artifacts, fail on generated-file drift.