Objective: create the smallest complete MarkdyScript scene: a title, a layout direction, declared nodes, and one reveal beat.
scene "Request Path" theme=paper
layout LR
browser WebApp
service ApiServer
beat reveal:
show $nodes stagger=60ms
| Step | Action | Why it matters |
|---|
| 1 | Add scene | Names the diagram and picks the semantic palette. |
| 2 | Add layout LR | Lets Markdy place nodes left-to-right without coordinates. |
| 3 | Declare every node | Flow lines can only reference ids that already exist. |
| 4 | Add a beat | Beats are the timeline sections that contain animation cues. |
Ready task: Add database Postgres to the scene. If show $nodes reveals all three nodes, move to Level 2.
Objective: choose node kinds that explain the architecture, then use readable ids so labels can be generated automatically.
user Customer
browser WebApp
gateway ApiGateway
service CheckoutApi
database OrdersDb
queue OrderEvents
| Kind family | Common kinds | Use when you mean |
|---|
| Client | user, browser, client | Humans, apps, and entry points. |
| Compute | service, api, worker | Code that handles requests or jobs. |
| Data | database, cache, bucket | State, files, and fast lookup layers. |
| Messaging | queue, topic, stream | Async events and background work. |
Prefer ids like CheckoutApi and OrdersDb. Markdy renders them as Checkout API and Orders DB, so quoted labels are only needed for unusual display text.
Ready task: Add cache RedisCache. If the rendered card has the cache role and a readable label, move to Level 3.
Objective: describe what happens between nodes using directed flow lines inside a beat. Labels belong after the target they describe.
WebApp -> CheckoutApi "POST /checkout"
CheckoutApi ~> OrderEvents "order.created"
WebApp <- CheckoutApi "201 Created"
| Operator | Use it for | Rendered intent |
|---|
-> | Calls, writes, reads | Solid request edge. |
<- | Returns and acknowledgements | Dashed response edge back to the caller. |
~> | Publishes and async jobs | Dotted event edge. |
-- | Static dependency | Thin relationship edge. |
Keep labels short and action-oriented: persist, enqueue, cache hit. Long prose belongs in surrounding docs, not edge labels.
Ready task: Add a RedisCache node and one CheckoutApi -> RedisCache "cache write" edge. If every id is declared and the flow renders, move to Level 4.
Objective: split a diagram into narrative beats so viewers can follow setup, traffic, async work, and emphasis in sequence.
beat highlight:
glow data color=#22c55e & focus CheckoutApi zoom=1.1
| Cue | Use it when | Common options |
|---|
show | Introducing nodes or groups. | stagger, dur |
glow | Marking the important path. | color, strength |
focus | Calling attention to one node. | zoom, dur |
& | Running two cues together. | Place it between cues on one line. |
Name beats after the story moment: intro, traffic, publish, finish. This makes generated scenes easier for people and LLMs to revise.
Ready task: Add a finish beat that glows CheckoutApi and OrdersDb together. If the story still reads in order, move to Level 5.
Objective: organize real systems into named tiers, then target each tier with one cue instead of repeating node ids everywhere.
group ingress: WebApp ApiGateway
group data: RedisCache OrdersDb
beat layout:
show ingress & show data stagger=70ms
| Pattern | Why it scales |
|---|
group ingress: ... | Names an architectural tier. |
show ingress | Reveals the whole tier without repeating ids. |
glow data | Highlights all related stateful components at once. |
Groups are especially useful in AI-generated diagrams because they give the model reusable targets and reduce typo-prone repeated node lists.
Ready task: Add an async group with a queue and worker, reveal it in layout, and send one ~> event into it. Then move to Level 6.
Objective: remove repeated flow choreography by defining a pattern once and applying it to different node pairs.
pattern lookup(client, store):
$client -> $store "lookup"
$client <- $store "result"
| Part | What to write | What happens |
|---|
| Definition | pattern lookup(client, store): | Declares reusable cue lines. |
| Placeholder | $client, $store | Marks values to substitute later. |
| Call site | use lookup(Api, Db) | Expands the pattern with concrete ids. |
Patterns should be small and meaningful. If the repeated action has a name people use in architecture reviews, it is a good pattern candidate.
Ready task: Add a second pattern called publish(app, queue) with one ~> event edge, then use it from CheckoutApi to the declared OrderEvents queue. Then move to Level 7.
Objective: tune visual meaning without changing the architecture: choose a theme, set direction, and style the path the viewer should remember.
style hot = fill=#f59e0b
service CheckoutApi style=hot
| Control | Use it for | Example |
|---|
theme | Overall palette. | paper, midnight |
layout | Scene reading direction. | LR, TB |
style | Persistent node styling. | style hot = fill=#f59e0b |
glow | Timeline emphasis. | glow CheckoutApi |
Use styles sparingly. One persistent highlight plus one final glow usually reads cleaner than styling every node.
Ready task: Switch the scene between paper/midnight/blueprint/graphite and TB/LR. If the story still reads clearly in both layouts, move to Level 8.
Objective: combine semantic nodes, groups, beats, flows, patterns, and emphasis into a real architecture explainer that can survive review.
scene "URL Shortener Production Flow" theme=paper width=1280 height=760
layout LR
group ingress: Visitor WebClient ApiGateway
group app: UrlShortener RedirectService
group data: HotUrlCache UrlMappingDb
| Production habit | Why it matters |
|---|
| Declare nodes first | Makes every later flow, group, and cue easy to validate. |
| Group by subsystem | Lets readers see ingress, app, data, and async tiers before traffic starts. |
| Use beats as story chapters | Keeps create, redirect, telemetry, and finish concerns separate. |
| End with emphasis | Confirms the main path and persistent state after the animation completes. |
When prompting an LLM, ask for this same order: scene metadata, nodes, groups, patterns, beats, then validation against declared ids.
Final task: Build a scene for one real system with at least eight nodes, three groups, four beats, one request, one response, one async event, one pattern, and one final glow. If it validates and a teammate can explain the architecture from the animation, you are ready for independent use.