Board code describes a whole whiteboard as text, like Mermaid describes a diagram: what's on the board (sections, sticky notes, Jira cards, links, diagrams) and how the parts connect. It never says where things go. Whiteboard+ lays the board out for you.
People write it, and so do AI agents (Claude, Cursor, ChatGPT…). Ask an agent for a design, paste what it writes onto a board, and the board builds itself.
Using it
- Paste it onto a board. Text that starts with
board,sectionorfolderis built as a board. - Or Insert → Board from code (or ⌘K / Ctrl+K, then type code), paste, and Build. If a line is wrong, nothing is built; the dialog shows the line and how to fix it.
- More (···) → Copy as code writes an existing board as board code, so you can change it as text or hand it to an agent.
The new parts are added beside what's already on the board.
A first example
board "Live order tracking"
section "Customer app" track=ui
note "Courier on a live map" as map
note "ETA that updates itself" color=Green
section "Services" track=system
note "Tracking service" as tracking
note "Redis: live locations" as redis
flow "Live map": map -> tracking "GPS ping" -> redis "write"
The rules
- One statement per line. Indenting is optional; it only makes the code easier to read.
- Everything after a
sectionline goes in that section, until the nextsection. - Text goes in double quotes. Inside quotes,
\nis a new line and\"is a quote. as namegives something an alias, so connections and flows can refer to it. An alias uses letters, digits,-and_, and each alias is used once.key=valuesettings come after the text, e.g.color=Green,track=api.- Lines starting with
#,//or%%are comments. - A board can hold up to 2,000 things.
Statements
| Statement | What it makes | Example |
|---|---|---|
board "Title" |
The board's title (optional, first line); style= for all its diagrams |
board "URL shortener" |
folder Name |
Puts the sections after it in a folder in the Sections sidebar | folder Backend |
section "Name" |
A section; things after it go in it | section "API" track=api step=3 |
note "Text" |
A sticky note | note "Redis cache" as cache color=Teal |
text "Text" |
Plain text (no note) | text "Draft: for review" size=28 |
jira KEY-1 |
A live Jira work item card | jira SHOP-142 as story |
link https://… "Title" |
A link card | link https://example.com/spec "The spec" |
api METHOD /path |
An API card: a row with its URL and status | api POST /api/v1/links status=201 |
an ```http block |
An API card with its req and res filled in | see below |
| a Mermaid diagram | An editable diagram (see below) | ```mermaid … ``` |
connect a -> b -> c |
Arrows between parts | connect api -> cache -> db |
flow "Name": a -> b + c |
A named flow, step by step | flow "Checkout": app -> api "POST /pay" -> pay |
section
section "Name" [as alias] [track=…] [color=…] [folder=…] [step=N]
track=gives the section its purpose, colour and icon (list below). A section with a track and no name is named after the track.color=overrides the colour:Grey,Blue,Teal,Green,Yellow,Orange,Red,Purple.folder=puts it in a folder in the Sections sidebar (or use afolderline before several sections).step=Nis its place in the presenting order (1, 2, 3…). Sections with the same step are presented together.
| Track | For |
|---|---|
requirements |
Functional and non-functional requirements |
estimates |
Users, requests per second, storage, bandwidth |
ui |
Screens, wireframes and design frames |
system |
Components and how they talk |
data |
Tables, stores and the data model |
api |
Endpoints and events |
deepdive |
The hard parts: IDs, caching, sharding, failures |
build |
Jira epics and stories |
release |
Rollout plan, flags and checklist |
run |
Dashboards, alerts and runbooks |
tradeoffs |
What you chose, what you didn't, and why |
note and text
note "Text" [as alias] [color=…]
text "Text" [as alias] [size=N]
Note colours: Yellow (default), Orange, Pink, Purple, Blue, Teal, Green, Grey.
jira and link
jira KEY-123 [as alias]
link https://example.com/page ["Title"] [as alias]
Jira cards show the work item's live status; they need Whiteboard+ installed in Jira on the same site.
APIs
An endpoint is an API card: one row with ▶, its URL and its status. Clicking ▶ opens rows under it,
status, req and res, each written in on the board like any text (the status pill follows the status
row). Write one on a line:
api METHOD /path ["Title"] [status=201] [as alias]
api "any URL" [status=200]
or fill its rows in with raw HTTP in an ```http block: the request line, its headers and body (the
req row); then the response, from HTTP/1.1 201 Created, and its body (the res row). ### lines separate
several.
section "API" track=api
```http as create
POST /api/v1/links
Content-Type: application/json
{ "url": "https://example.com/page", "alias": "promo" }
HTTP/1.1 201 Created
{ "code": "promo" }
```
api GET /{code} status=302 as redirect
connect and flow reach an API card by its alias or, in quotes, by "POST /api/v1/links" or its path. On a
board, /api makes an empty row to type the URL in; pasting a curl command, raw HTTP or an OpenAPI / Swagger
spec makes filled-in cards; and pasting a curl command into a card fills that card in.
Diagrams
A Mermaid diagram in a fenced block becomes shapes you can move and edit:
section "Data" track=data
```mermaid
erDiagram
USER ||--o{ LINK : owns
LINK ||--o{ CLICK : gets
```
Diagrams are drawn in Excalidraw's hand-drawn style. For Mermaid's look instead, add style=mermaid to the
diagram (```mermaid style=mermaid) or to the board (board "Title" style=mermaid); style=sketch
asks for the hand-drawn look where the board says otherwise. (Mermaid code pasted straight onto a board, not
in board code, keeps Mermaid's look.)
flowchart, sequenceDiagram, erDiagram, classDiagram, stateDiagram-v2 and the other Mermaid types
work. A diagram can also go without the fence: its first line (e.g. flowchart LR) with its lines indented
under it. A diagram's nodes can be used in connect and flow by their id or label.
connect
connect a -> b -> c [flow="Name"]
Draws arrows from each part to the next. A part is named by its alias, a Jira key, a diagram
node (id or label), or, in quotes, a note's text or a section's name:
connect "Courier on a live map" -> Tracking. flow="Name" puts the arrows in a named flow.
flow
flow "Name": a -> b "label" -> c + d -> e
A named path through the design, such as one request from the UI to the database. On the board, choosing a flow highlights its parts and greys out the rest, and presenting a flow goes step by step.
->goes to the next step.+puts parts side by side at the same step (they happen together).- A quoted word after a part labels the arrow into it:
gw "POST /links". - A part can be in many flows. Each flow is traced and presented on its own.
Writing good board code (for people and agents)
- Start with
board "Title", then onesectionper concern, in reading order, each with astep=. Use tracks for system design: requirements → estimates → api → system → data → deepdive → tradeoffs → run. - A system design is diagrams, not only notes. Notes hold requirements, numbers, endpoints and
decisions; the design itself is drawn:
- the architecture as a
flowchart LRin a "High-level design" section: asubgraphper tier (clients, edge, services, storage, async),[(…)]for databases and caches,[[…]]for queues, and arrows for who calls whom; - each important request path as a
sequenceDiagramin its own section (withaltfor branches such as a cache hit or miss); - the data model as an
erDiagramwith keys and types; - a hard part (ID generation, sharding, fan-out) as a small diagram of its own in the deep dive.
- the architecture as a
- Add a
flowper user action over the architecture's node ids (flow "Redirect": User -> LB -> Read -> Cache "hit?" -> DB "on a miss"). Choosing the flow on the board lights up that path in the diagram, and presenting it walks through it step by step. Label the arrows with what's sent. - Give an alias to every note that a
floworconnectuses; diagram nodes are referred to by their id. Keep node ids unique across the board's diagrams. - Keep notes short (one idea). Write endpoints as API cards, not notes: an
```httpblock for the important ones (with the request and response bodies),api METHOD /path status=…for the rest. - Use
connectfor relations that aren't a path, such as an API note pointing at the service behind it. - Use colours to mean something (e.g. Green for functional requirements, Blue for non-functional, Red for risks).
- Output only the code, in one block, with no prose inside it.
Full example: a URL shortener
The example is at url-shortener.txt. Paste it onto a board to see a full system design: requirements, estimates and the API as notes; the architecture, the create and redirect paths, the data model and the key generation service as diagrams; trade-offs; and four flows that light up paths through the architecture.
board "URL shortener: system design"
# 1. What it must do
section "Requirements" track=requirements step=1
text "Functional"
note "Shorten a long URL to a short, unique code" color=Green
note "Redirect a short code to its long URL" color=Green
note "Custom alias and expiry, both optional" color=Green
text "Non-functional"
note "Redirects: highly available, p99 < 50 ms" color=Blue
note "Codes are not guessable in sequence" color=Blue
note "Read heavy: 100 redirects per new link" color=Blue
# 2. How big it gets
section "Estimates" track=estimates step=2
note "Writes\n100M links / month\n≈ 40 / s (peak 400 / s)"
note "Reads (100:1)\n≈ 4,000 / s (peak 40k / s)"
note "Storage, 5 years\n6B links × 500 B ≈ 3 TB" color=Blue
note "Cache: hot 20% of a day's reads\n≈ 35 GB of RAM" color=Teal
note "Code length\n62^7 ≈ 3.5 trillion: 7 chars is plenty" color=Green
# 3. The API: a card per endpoint. Click ▶ (or select it and press →) for its status, headers, req and res
section "API" track=api step=3
```http as api_create
# Create a short link
POST /api/v1/links
Authorization: Bearer <api key>
Content-Type: application/json
{ "url": "https://example.com/a/very/long/page", "alias": "promo", "expiresAt": "2027-01-01" }
HTTP/1.1 201 Created
Location: https://sho.rt/promo
{ "code": "promo", "shortUrl": "https://sho.rt/promo" }
# Redirect
GET /{code}
HTTP/1.1 302 Found
Location: https://example.com/a/very/long/page
# Click stats for a link
GET /api/v1/links/{code}/stats
Authorization: Bearer <api key>
HTTP/1.1 200 OK
Content-Type: application/json
{ "clicks": 1342, "byCountry": { "IN": 801, "US": 312 }, "byDay": [ { "day": "2026-11-13", "clicks": 96 } ] }
api DELETE /api/v1/links/{code} "Delete a link (owner only)" status=204 as api_delete note "Every write needs an API key; rate limited per key. 409 when an alias is taken, 404 for unknown or expired codes" color=Orange
4. High-level design: the architecture
section "High-level design" track=system step=4
flowchart LR
subgraph Clients
User[Browser / mobile app]
end
subgraph Edge
DNS[DNS + CDN]
LB[Load balancer]
end
subgraph App[Application tier]
Write[Shorten service]
Read[Redirect service]
end
subgraph Keys[Key generation]
KGS[Key generation service]
KeyDB[(Key DB: unused / used)]
end
subgraph Storage
Cache[(Redis cache)]
DB[(Links DB: Cassandra)]
end
subgraph Async[Background]
Queue[[Kafka: click events]]
Stats[Analytics workers]
OLAP[(ClickHouse)]
Sweeper[Expiry cleanup]
end
User --> DNS --> LB
LB --> Write
LB --> Read
Write --> KGS --> KeyDB
Write --> DB
Read --> Cache
Read --> DB
Read --> Queue --> Stats --> OLAP
Sweeper --> DB
5. Request paths, step by step
section "Create a short link" track=system step=5
sequenceDiagram
participant U as Client
participant S as Shorten service
participant K as Key generation service
participant D as Links DB
participant R as Redis
U->>S: POST /api/v1/links { url }
S->>S: validate URL, check API key quota
S->>K: next key
K-->>S: "aZ3kP9q" (from a pre-loaded batch)
S->>D: INSERT code, url, owner, expiresAt
S->>R: SET code → url (warm the cache)
S-->>U: 201 https://sho.rt/aZ3kP9q
section "Redirect" track=system step=6
sequenceDiagram
participant U as Client
participant G as Redirect service
participant R as Redis
participant D as Links DB
participant Q as Kafka
U->>G: GET /aZ3kP9q
G->>R: GET aZ3kP9q
alt cache hit
R-->>G: long URL
else cache miss
G->>D: SELECT url WHERE code = aZ3kP9q
D-->>G: long URL (or not found)
G->>R: SET aZ3kP9q (TTL 24h)
end
G-)Q: click event (async)
G-->>U: 302 Location: long URL
6. Data model
section "Data model" track=data step=7
erDiagram
USER ||--o{ LINK : creates
LINK ||--o{ CLICK : receives
USER {
string user_id PK
string email
string api_key
datetime created_at
}
LINK {
string code PK "7 chars, base62"
string long_url
string user_id FK
datetime created_at
datetime expires_at
}
CLICK {
string code FK
datetime at
string country
string referrer
}
note "Key-value access only (code → URL), billions of rows: a NoSQL store like Cassandra or DynamoDB" color=Teal
7. The hard parts
section "Deep dive" track=deepdive step=8
flowchart TB
subgraph KGS[Key generation service]
Gen[Generate random base62 keys offline] --> Unused[(Unused keys)]
Unused -->|load 1,000 at a time| Mem[Keys in memory]
Mem -->|hand out one per request| Used[(Used keys)]
end
note "Why a key service: no collisions and no DB lookup on create. Hashing the URL (MD5 → base62) needs collision checks." color=Blue note "Partitioning: hash(code) spreads keys evenly; range-based by first letter makes hot shards" color=Blue note "Cache: LRU, read-through; 20% of links take 80% of traffic. Cache 'not found' too, to stop scans" color=Teal note "KGS is a single point of failure: run a standby replica; a crash loses only the keys in memory" color=Red note "Expiry: delete lazily on read, plus a nightly sweep; expired keys go back to the pool" color=Grey
8. Choices made
section "Trade-offs" track=tradeoffs step=9 note "302 not 301: every click reaches us, so analytics count it, at the cost of more traffic" note "Clicks go through Kafka: a redirect never waits for analytics; numbers lag about a minute" note "Pre-generated keys vs hashing: simpler, faster writes, but KGS must be highly available"
Flows over the architecture: pick one in Sections → Flows to light up its path
flow "Create a short link": User -> LB "POST /api/v1/links" -> Write -> KGS "next key" + DB "insert" flow "Redirect": User -> DNS "GET /{code}" -> LB -> Read -> Cache "hit?" -> DB "on a miss" flow "Count a click": Read -> Queue "click event" -> Stats -> OLAP flow "Expire old links": Sweeper -> DB "delete expired"
connect api_create -> Write connect api_get -> Read connect api_stats -> OLAP connect api_delete -> Write
For AI agents
Ask Claude, ChatGPT, Cursor or any other agent for a board, paste what it writes onto a board, and the board builds itself. Give it one of these:
- The agent skill (Claude Code, Claude, Cursor and others): migratly.dev/whiteboard/board-code/SKILL.md
- This page as Markdown, for any agent: migratly.dev/whiteboard/board-code.md
In a chat (ChatGPT, Claude, Gemini), the simplest ask is: “Read migratly.dev/whiteboard/board-code/SKILL.md,
then write board code for …”, then Copy its code block and paste it onto a board. The skill
tells the agent to keep the whole board in one block, with diagrams and APIs written without ```
inside it: a ``` inside a chat answer breaks it into pieces, and the diagrams are lost when it’s copied.
Copied with the chat’s fences around it, it still builds.
To install the skill:
- Claude Code: save it as
~/.claude/skills/whiteboard-board-code/SKILL.md(or in a project's.claude/skills/whiteboard-board-code/). - Claude (claude.ai): put
SKILL.mdin a folder namedwhiteboard-board-code, zip the folder, and upload it in Settings → Capabilities → Skills. - Cursor: save it as
.cursor/rules/whiteboard-board-code.mdc. - Any other agent: give it the Markdown link and ask it to "write Whiteboard+ board code for …".