+id: UUID; +total: Money; | +addItem(item); +checkout(); ]


## Syntax essentials

### Nodes (boxes)

- Basic: `[A]`
- With compartments (title | attributes | methods): `[A|x; y|do();]`
- Escape newlines with actual newlines (preferred) or `\n` when needed.

### Relationships (common)

```text
[A]->[B]        # association / dependency
[A]-->[B]       # dotted
[A]-:>[B]       # composition-like (varies by style)
[A]<-[B]        # reverse arrow
[A]-[B]         # line without arrow

If arrow semantics are ambiguous, prefer clear labels:

[API]->[DB]
[API] "reads/writes" -> [DB]

Cardinalities / labels

[Customer] 1->* [Order]
[Order] 1->* [OrderLine]

Grouping

[<frame> Payments|
  [API]
  [Worker]
]

[API]->[Worker]

Common containers:

<frame>: big box grouping
<package>: package-like grouping
<actor>: actor stick figure

Styling / directives

Add directives at the top using #:

#direction: right
#spacing: 40
#ranker: tight-tree

[Client]->[API]

Common directives:

#direction: right|down
#spacing: <number>
#padding: <number>
#ranker: network-simplex|tight-tree|longest-path

Workflow: generate a diagram from a description

Identify the diagram type:
- Class/data model → boxes with compartments + inheritance/associations
- Architecture/services → frames/packages + arrows + labeled edges
- Flow/steps → simple boxes + arrows; keep it readable
Choose names:
- Use stable nouns for nodes (AuthService, TokenStore, Frontend).
- Keep node names short; put details in compartments or labels.
Produce nomnoml code:
- Start with #direction: right for architecture diagrams.
- Use frames/packages to group by bounded context.
- Add labels for anything non-obvious.
Iterate:
- If diagram is too dense, split into multiple diagrams (by subsystem).

Rendering (tool)

If a rendered asset is needed, use the nomnoml tools instead of CLI.

Option A: quick preview

Use the tool to render directly in chat:

nomnoml-display with inline source for a quick preview.

Option B: render to SVG

Use the tool to render and optionally write a file:

nomnoml-render with inline source and optional outputFile.
nomnoml-render-file with inputFile and optional outputFile.

If rendering isn’t required, still produce the .nomnoml source file so it can be rendered later.

Patterns

Architecture sketch (recommended default)

#direction: right

[<actor> User]->[WebApp]

[<frame> Backend|
  [API]
  [Worker]
]

[WebApp]->[API]
[Worker]->[DB]
[API]->[DB]

[DB]

Class diagram with inheritance

[<abstract> Animal|+name: string|+speak()]
[Dog|+breed: string|+speak()]
[Cat|+color: string|+speak()]

[Animal]<:-[Dog]
[Animal]<:-[Cat]

Entity relationship (simple)

#direction: down

[User|id; email]
[Session|id; userId; expiresAt]

[User] 1->* [Session]

When asked to “update an existing diagram”

Preserve existing node names unless there’s a clear rename.
Apply the smallest diff:
- add one box/edge at a time
- keep direction/ranker consistent
If you change meaning, update edge labels to stay explicit.

nomnoml

nomnoml

Quick start

Minimal diagram

Typical class box

More from knoopx/pi

podman

jujutsu

nix-flakes

scraping

jscpd

nix