Skip to content
Kekonic DiagramsKekonic Diagrams

Meet Kekonic Diagrams

You already know what the system does. Name the parts that matter and how they relate. Kekonic Diagrams measures the labels, places the nodes, routes the connections, and redraws whenever the source changes, with no coordinates to maintain.

Edit source — diagram updates live
Source

The idea in one minute

Section titled “The idea in one minute”

A .kdiagram file contains meaning, not coordinates:

checkout.kdiagram
diagram "Checkout" {
  direction LR


  group app "Application" {
    api: gateway "Public API"
    checkout: service "Checkout"
  }


  orders: database "Orders"
  events: broker "Domain events"


  api -> checkout "place order"
  checkout -> orders "save"
  checkout => events "OrderPlaced"
}

Read it from top to bottom:

  1. diagram gives the model a name.
  2. api: gateway "Public API" declares a node: stable ID, semantic kind, human label.
  3. group says two nodes belong to the same boundary.
  4. -> describes a direct interaction; => describes an event.
  5. direction LR asks the layout engine to make the main flow read left to right.

There are no x and y positions to maintain. That is the bargain: less manual control for source that stays readable and cheap to change in review.

Where it fits

Section titled “Where it fits”

Kekonic Diagrams is for diagrams whose structure matters more than freehand composition:

  • software architecture and service maps
  • event-driven systems and data pipelines
  • operational and business workflows
  • database relationships
  • request traces and sequence diagrams
  • anything that should live in a repository, documentation site, or CI pipeline

The same source can become a portable SVG, a live browser diagram, or an animated explanation.

If you need workshops, pixel nudging, Gantt charts, or full UML coverage, start elsewhere. See Is Kekonic Diagrams right for you?.

Author wherever you already work

Section titled “Author wherever you already work”

The text model stays authoritative. Presentation controls in Studio write back to the DSL instead of hiding state in the editor:

  • Hosted Studio: fastest start. Browser-only, local .kdiagram files, no account.
  • Local Studio: same UI from the CLI, with repository watching and opt-in writes.
  • VS Code and compatible editors: language intelligence, preview, and export beside your code.
  • Any text editor: CLI and language server when you prefer your own toolchain.

A file can move between these workflows without changing meaning or locking you to a host.

Deliver where readers already look

Section titled “Deliver where readers already look”

Authoring and delivery are separate choices:

  • self-contained SVG for READMEs, wikis, slides, and CI artifacts
  • fenced blocks through Remark or Markdown-it for documentation sites
  • .kdiagram imports through Vite and compatible bundlers
  • React or the web component when readers need pan, zoom, themes, or playback
  • CLI validation and render for whole repositories

See Publish diagrams when you are ready to pick a destination.

What automatic layout can and cannot do

Section titled “What automatic layout can and cannot do”

Kekonic Diagrams measures labels before placing nodes. Groups participate in layout instead of becoming decorative boxes afterward. Connections attach to node boundaries; routed edges can get crossing treatment when a graph gets dense.

That does not mean every graph will look perfect. Dense or weakly structured models still look poor. Reach for semantic structure (groups, direction, density, edge meaning), or split the view before you try to micromanage geometry.

Choose your next step

Section titled “Choose your next step”

The language reference is for lookup. It is intentionally not the first thing you need to read.