dgmo-diagramming

name	dgmo-diagramming
description	Use when the user asks for a diagram, chart, sequence diagram, flowchart, ER diagram, org chart, kanban, sitemap, infra/architecture diagram, or any visual based on the DGMO diagram markup language. Provides syntax, MCP tool guidance, and rendering/sharing workflows.

DGMO Diagram Language

Use dgmo tools to create, render, and share diagrams. dgmo is a text-based diagram markup language that renders to SVG/PNG.

DGMO AI Core

Generated from language-reference.md — the anti-patterns and 50-type index below are identical across every DGMO AI surface.

Disambiguation — where DGMO diverges from LLM priors

LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the most common parse errors:

• No colons in declarations, directives, tags, or data rows. bar Revenue (not bar: Revenue); series Cloud blue, Legacy red (not series: ...); North 850 (not North: 850); tag Team as t (not tag: Team). A colon binds a value only in metadata (key: value), class/function type separators, and a few scoped spots — see §26.
• No Mermaid arrow-labels. Put the label between the dashes: A -Login-> B, never A -> B: Login. Sequence: -> sync, ~> async; left-to-right only — no <- / <~.
• No indented edges on a map. Every map connection is ONE full line — JFK ~daily~> LAX; for a hub repeat the origin per spoke (JFK ~daily~> LHR, …). A bare source with indented -> dest legs errors as Malformed edge; indented legs are valid ONLY inside a route block (an ordered stop→stop voyage). Edge endpoints auto-create their POIs — don't add separate poi lines for places already in an edge.
• No | metadata delimiter (removed 0.18.0 → E_PIPE_OPERATOR_REMOVED). Use same-line Name key: value, k2: v2 or indented key: value. (| survives only in wireframe {A | B} dropdowns, in-arrow label text, and quoted names.)
• No removed participant keywords. Do not write X is a service / external / frontend / networking / gateway — these were removed and error. A bare name renders the default shape; for a typed glyph use is a person / is a database / is a queue.

• Colors are a closed set of EXACTLY these 11 — nothing else is a color. Valid colors, the complete list: red, orange, yellow, green, blue, purple, teal, cyan, gray, black, white. That is the entire universe of DGMO colors — there are no others. Do NOT use hex (#1f77b4), rgb(...), hsl(...), or ANY CSS color name: crimson, royalblue, navy, pink, lime, magenta, indigo, gold, salmon, turquoise, violet, etc. are ALL invalid — they are rejected and the element falls back to an auto-assigned color. When you want a color outside the 11, map it to the nearest one: crimson/scarlet→red, royalblue/navy/cobalt→blue, pink/magenta/violet/indigo→purple, lime/olive→green, gold/amber→yellow, turquoise→teal. Apply a color as a trailing token (Done green) or after a category/group bracket ([North America] red). Named colors are mandatory because they re-resolve per active palette + light/dark theme; a hardcoded value never would.

• Show-everything is the default. Every label / value / percent renders by default. Emit no-name / no-value / no-percent / no-* ONLY when the user explicitly asks to hide something — never defensively.
• // comments only (never #). Indentation closes blocks — never end.
• Declare before reference. An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid Duplicate node warnings.
• No reference scaffolding in output. Emit only DGMO source. This doc is organized with HTML-comment anchors (the TYPE, TIPS, and AI-CORE markers, each wrapped in comment delimiters); never copy any such <!-- … --> comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an Unexpected line warning. (DGMO's only comment form is //.)

Two traps in the other direction (DGMO wants a colon / a space where you might not expect):

• Infra node properties REQUIRE the colon — cache-hit: 80%, instances: 3, max-rps: 8000, latency-ms: 45. But top-level infra options are space-separated (default-rps 100). Don't conflate them.
• ER columns are space-separated — id int pk, email varchar (the one SQL-DDL carve-out; everything else indented-typed uses a colon).

Idiomatic example — color via tags, metadata on the declaration line, indented edges:

boxes-and-lines Service Map
tag Team as t
  Platform blue
  Product green
active-tag Team

API Gateway t: Platform
  -routes-> Orders
  -routes-> Billing
Orders t: Product
Billing t: Product

Make it look good — authoring guidance

Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise:

• Always title it. Every diagram gets a short title on the type-declaration line (flowchart Checkout Flow, sequence Checkout, boxes-and-lines Service Map) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none.

• Categorize and color — by default, not only when obvious. Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a tag group, never ad-hoc per-node colors: declare tag <Axis> as t (the name is a single word — tag TrustZone as tz — or quote a multi-word name: tag "Trust Zone" as tz), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set active-tag <Axis>, then assign each item Node t: <Category> (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. Buckets, not name tags — never 1:1. A tag group must have fewer values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a cache and a database are both datastore; a caller and a gateway are both client; two microservices are both service). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color.

• Keep labels short. A few words per node. Move detail into notes or metadata, never a full sentence inside a label.
• Let the defaults show. Don't add no-* opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color.
• Pick a fitting direction. Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction).

Chart-type index (45) — pick the type, then fetch its section

id	when to use
sequence	message / interaction flows over time
flowchart	decision trees and process flows
state	state-machine / lifecycle transitions
class	UML class hierarchies
er	database schemas and relationships
c4	system architecture (context / container / component / deployment)
infra	infrastructure traffic flow with RPS computation
boxes-and-lines	general-purpose node-edge diagrams with groups and tags
sitemap	site / app navigation structure
mindmap	radial hierarchy of ideas from a central topic
org	reporting hierarchy
family	family tree / genealogy: unions (couples), children, remarriage, adoption, GEDCOM-style metadata
bracket	single-elimination tournament bracket: winners auto-advance; seed the field for a day-0 skeleton or list results casually; two sides mirror to a championship
kanban	task-board columns
gantt	project scheduling with task dependencies and milestones
pert	project network with three-point estimates and critical path
swimlane	cross-functional process flow with lanes, phases and gateways (BPMN-style)
version-control	git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style)
timeline	events, eras, and date ranges
event-line	annotated narrative timeline — events on a line with descriptions, optionally not to scale (NOT the date-scaled timeline)
body	human anatomy figure annotated by muscle name — for medical, exercise, and educational diagrams
journey-map	UX flow with emotion scores, phases, annotations
cycle	cyclical process (PDCA, OODA, DevOps loops)
raci	tasks × roles responsibility matrix; variant (RACI / RASCI / DACI) is inferred from the markers used
tech-radar	technology adoption quadrants (adopt / trial / assess / hold)
quadrant	2×2 positioning matrix
pyramid	stacked hierarchy of layers (Maslow, DIKW)
ring	concentric rings of nested categories
treemap	nested rectangles sized by value (budgets, disk usage, portfolios)
block	author-controlled grid of nested, collapsible blocks (system / architecture layouts)
sketch	GUI-first free-placement canvas: uniform shapes on a snap grid, arrows, tags (markup is app-generated)
goal	single progress-toward-a-target value (now vs target) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas
countdown	live "N days until X" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type
clock	live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line
map	geographic concept map: regions, points, routes
wireframe	low-fidelity UI layout with panels and controls
bar	categorical comparisons (multi-series via stack / group)
line	trends over time (multiple series via a series block; filled via fill; dual y-axes via y-label / y-right-label)
pie	part-to-whole proportions (ring/doughnut via hole)
radar	multi-dimensional metrics
polar-area	radial bar chart
scatter	2D points or bubble chart
heatmap	matrix intensity
funnel	conversion pipeline
sankey	flow / allocation
arc	network relationships (linear, or circular via layout chord)
slope	change between two periods
venn	set overlaps
wordcloud	term-frequency
function	mathematical expressions (colon required: f(x): x^2)

Need more than the index gives you? Fetch the per-type section: MCP get_language_reference(type) / get_examples(type), or read that type's section below. The suggest_chart_type tool returns the chosen type's section automatically.

When the type isn't obvious, ask — don't guess. Call suggest_chart_type first. If it returns an ⚠️ ASK THE USER directive (the request is ambiguous between candidates, or nothing matched), present those candidate options to the user and wait for their pick before generating — never silently choose. A confident result (high/medium) you can proceed with.

Common examples (curated, parse-clean)

The most common types, inline so you can generate them without a fetch. For the other 42, get the per-type section (see below).

journey-map

journey-map A Cabin Boy's First Voyage

persona Squidlips Sam color: blue
  Greenhorn cabin boy, first time at sea
  Sworn to the crew but quietly terrified

[Signing On]
  Sign the articles score: 4, emotion: Hopeful
    description: Captain reads the code aloud — pay shares, no women aboard, lights out at 8

[The Tempest]
  Caught in a squall off the reef score: 1, emotion: Terrified
    pain: Two crewmates lost overboard before dawn
    thought: Maybe the merchant fleet wasn't so bad after all
  Dawn, and she still floats score: 3, emotion: Relieved

[The Prize]
  Strike the colors score: 5, emotion: Triumphant
    description: Heavy with silver from the Veracruz mines

[Homecoming]
  Bury a share on the island score: 5, emotion: Proud
    thought: Three doubloons hidden where only he can find them
  Back to the Rusty Anchor score: 4, emotion: Content
    opportunity: Next time he signs on as a full hand, not a boy

c4

c4 Pirate Treasure Map System

tag Scope as sc
  Crew blue
  External gray

Captain is a person description: Commands the fleet and plans raids

TreasureMap is a system description: Tracks buried treasure locations and raid intelligence
  -Views treasure locations-> Captain
  -Sends raid alerts [carrier pigeon]-> Lookout

  containers
    ChartRoom is a container description: Interactive sea chart with treasure markers, tech: Parchment
      -Queries treasure data [secret code]-> Vault

    Vault is a container description: Encrypted treasure ledger and coordinates, tech: Iron Chest
      -Reads/writes [quill and ink]-> TreasureLog

    TreasureLog is a container description: "Stores locations, guard counts, and loot inventories", tech: Leather-Bound Tome

Lookout is an external description: Crow's nest spotter on allied ships, sc: External
  ~Relays sightings to~> Captain

deployment
  Flagship
    container ChartRoom
    container Vault
  SecretCave
    container TreasureLog

er

er Pirate Fleet

ships
  id int pk
  name varchar
  ship_type varchar
  cannons int
  1-aboard-* crew_members
  1-1 captains
  1-carries-* treasure

captains
  id int pk
  name varchar
  ship_id int fk
  bounty int
  ?-frequents-1 ports
  *-has-1 crew_members 

crew_members
  id int pk
  name varchar
  ship_id int fk
  role varchar nullable

treasure
  id int pk
  name varchar
  value int
  ship_id int fk, nullable

ports
  id int pk
  name varchar
  region varchar unique
  1-docks-* ships

class

class Ship Class Hierarchy

interface Vessel
  + sail(): void
  + anchor(): void

abstract Ship implements Vessel
  # name: string
  # crew: number
  + getName(): string

Galleon extends Ship
  - cannons: number
  + fire(): void

Sloop extends Ship
  - speed: number
  + flee(): void

enum ShipType
  Galleon
  Sloop
  Frigate

Ship
  -> ShipType has type

sequence

sequence Treasure Hunt App

tag Concern as c
  Search blue
  Claims green
  Notifications orange

User is an actor

[Treasure Service]
  TreasureAPI
  MapDB is a database
  NotifyQueue is a queue

User -Search nearby loot-> WebApp
WebApp -GET /treasures?nearby-> TreasureAPI c: Search
TreasureAPI -Find within 5nm-> MapDB c: Search
note
  - check location
  - use compass
MapDB -3 results-> TreasureAPI
TreasureAPI -locations-> WebApp
WebApp -Show treasure map-> User

== Claim ==

User -Claim chest #42-> WebApp
WebApp -POST /claim-> TreasureAPI c: Claims
if chest available
  TreasureAPI -Set status = claimed-> MapDB c: Claims
  MapDB -OK-> TreasureAPI
  TreasureAPI ~treasure.claimed~> NotifyQueue c: Notifications
  TreasureAPI -Claim accepted-> WebApp
  WebApp -500 doubloons earned!-> User
else
  TreasureAPI -409 Already claimed-> WebApp
  WebApp -Too slow, matey!-> User

state

state Ship Battle Lifecycle

[*] -> Sailing

Sailing
  -enemy spotted-> BattleStations

[Losses] gray
  Captured -> [*]
  Sinking -> [*]

[Aftermath] teal
  Victorious
    -loot taken-> Sailing

  Retreating
    -escaped-> Sailing
    -caught-> Captured

[Combat] red
  Engaging
    -alongside-> Boarding
    -hull breach-> Sinking
    -outgunned-> Retreating

  Boarding
    -crew wins-> Victorious
    -crew loses-> Captured

BattleStations
  -in range-> Engaging
  -enemy retreats-> Sailing

infra

infra Pirate Communication Network

tag Fleet as f
  Blackbeard red
  Bonny purple
  Rackham blue

Edge
  rps: 200
  -> SignalFlags

SignalFlags f: Blackbeard
  description: Flag semaphore relay — ship-to-ship messaging
  latency-ms: 30000
  -> Flagship
  -> ScoutShip

Flagship f: Blackbeard
  description: Command vessel — decrypts and routes all intelligence
  instances: 1
  max-rps: 50
  latency-ms: 5000
  -> CarrierPigeons
  -> RumRunner

ScoutShip f: Bonny
  description: Fast sloop for reconnaissance
  instances: 2
  max-rps: 30
  latency-ms: 8000
  -> Flagship

CarrierPigeons f: Rackham
  description: Long-range bird relay — messages to allied ports
  buffer: 100
  drain-rate: 12
  retention-hours: 72
  -> TavernNetwork

[Allied Ports]
  instances: 3

  TavernNetwork f: Rackham
    description: Dockside tavern informants across the Caribbean
    max-rps: 20
    latency-ms: 86400000

RumRunner f: Bonny
  description: Smuggler supply line — moves coded messages in rum barrels
  concurrency: 4
  duration-ms: 172800000
  -> TavernNetwork

gantt

gantt Blackbeard's Blockade — 1718

start 1718-05-01
today-marker 1718-05-15

tag Role as r
  Command red
  Crew blue
  Captives orange

marker 1718-05-14 Ransom Deadline red
era 1718-05-08 -> 1718-05-17 Blockade Active blue

[Preparation] r: Command
  Provision Ship 3d r: Crew, progress: 100
    -> Anchor Fleet 2d r: Crew, progress: 100
  Scout Harbor 3d r: Crew, progress: 100
    -> Position Cannons 3d r: Crew, progress: 100
  Recruit Hands 5d r: Crew, progress: 100

+7d [Blockade] r: Crew
  Seize Merchants 4d progress: 100
    -> Hold Hostages 5d r: Captives, progress: 60
  Patrol Perimeter 9d progress: 75
  Demand Medicine 4d r: Command, progress: 100
    -> Threaten Executions 3d? r: Command, progress: 90

+17d [Resolution] r: Command
  Receive Ransom 2d r: Captives
    -> Release Prisoners 1d r: Captives
      -> Set Sail 0d
  Burn Evidence 2d r: Crew

Fetch more: call get_language_reference(type) for a type's full syntax and get_examples(type) for starter templates. suggest_chart_type returns the chosen type's reference automatically.

Output — where the diagram goes

Always save the .dgmo source to <name>.dgmo in the working directory — it's the editable deliverable; the app/URL just displays it. Never render a PNG/SVG unless the user explicitly asks for an image.

Decide the visual output once per session with check_app_installed:

1. App installed → save the source, then open_in_app({ dgmo, filePath: "<abs path to the saved file>" }). The app opens that file, so in-app edits autosave back to it — one source of truth, live re-render. Best UX. Don't open an online URL and don't render a PNG.
2. App not installed → share_diagram returns a https://online.diagrammo.app/... URL; open it. Same chart + editor view in the browser. Preferred fallback.

Other tools (use only when the user asks for them): 3. render_diagram — PNG or SVG to a file path. Use when the user wants an image artifact (export, embed, attach). 4. generate_report — renders multiple diagrams into an HTML report with table of contents. 5. preview_diagram — local HTML preview in the browser; also the multi-diagram side-by-side tool. 6. list_chart_types / get_language_reference — discovery; call get_language_reference before generating an unfamiliar chart type.

When to use dgmo

• Architecture diagrams, sequence diagrams, flowcharts
• Data charts (bar, line, pie, scatter, heatmap, etc.)
• ER diagrams, class diagrams, org charts
• Project roadmaps, kanban boards, gantt charts, timelines
• Responsibility matrices (RACI / RASCI / DACI), journey maps, pyramids, rings, mindmaps, wireframes, tech radars

Quick syntax reference

Sequence diagram

sequence Auth Flow

User -Login-> API
API -Find user-> DB
DB -user-> API
  if valid
    API -200 OK-> User
  else
    API -401-> User

Flowchart

flowchart Process

(Start) -> <Valid?>
  -yes-> [Process] -> (Done)
  -no-> /Get Input/ -> <Valid?>

Bar chart

bar Revenue

North 850
South 620
East 1100

ER diagram

er Schema

users
  id int pk
  email varchar

posts
  id int pk
  user_id int fk

users 1-writes-* posts

Org chart

org

CEO
  VP Engineering
    Team Lead A
    Team Lead B
  VP Marketing

Infra chart

infra

edge
  rps: 10000
  -> CDN

CDN
  cache-hit: 80%
  -> LB

LB
  -> API split: 70%
  -> Web split: 30%

API
  instances: 3
  max-rps: 500
  latency-ms: 45

All chart types

Data charts: bar, line, pie, radar, polar-area, scatter, sankey, function, heatmap, funnel, treemap

Visualizations: slope, wordcloud, arc, timeline, event-line, venn, quadrant, tech-radar, cycle, pyramid, ring, map

Diagrams: sequence, flowchart, state, class, er, org, kanban, c4, sitemap, infra, gantt, pert, boxes-and-lines, block, swimlane, version-control, mindmap, wireframe, journey-map, raci

Common patterns

• First line: chart type keyword (e.g. sequence, flowchart, bar), optionally followed by a title (bar Revenue)
• // comment — only // comments (not #)
• (colorname) — inline colors on data series, tag values, kanban columns: Label(red) 100
• series A(red), B(blue) — multi-series with colors

Rendering via CLI

dgmo file.dgmo -o output.svg       # SVG
dgmo share file.dgmo               # shareable link (copied to clipboard)
dgmo file.dgmo --json              # structured JSON output

Mistakes to avoid

• Don't use # for comments — use //
• Don't use end to close sequence blocks — indentation closes them
• Don't use hex colors in section headers — use named colors
• Start the file with the chart type keyword when content is ambiguous
• Sequence arrows: -> (sync), ~> (async) — always left-to-right

Full reference: call get_language_reference MCP tool or visit diagrammo.app/docs