← Whiteboard+ for Confluence
Whiteboard+

Board code

Whiteboards written like Mermaid, by people and AI agents.

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

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

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 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.

Writing good board code (for people and agents)

  1. Start with board "Title", then one section per concern, in reading order, each with a step=. Use tracks for system design: requirements → estimates → api → system → data → deepdive → tradeoffs → run.
  2. 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 LR in a "High-level design" section: a subgraph per tier (clients, edge, services, storage, async), [(…)] for databases and caches, [[…]] for queues, and arrows for who calls whom;
    • each important request path as a sequenceDiagram in its own section (with alt for branches such as a cache hit or miss);
    • the data model as an erDiagram with keys and types;
    • a hard part (ID generation, sharding, fan-out) as a small diagram of its own in the deep dive.
  3. Add a flow per 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.
  4. Give an alias to every note that a flow or connect uses; diagram nodes are referred to by their id. Keep node ids unique across the board's diagrams.
  5. Keep notes short (one idea). Write endpoints as API cards, not notes: an ```http block for the important ones (with the request and response bodies), api METHOD /path status=… for the rest.
  6. Use connect for relations that aren't a path, such as an API note pointing at the service behind it.
  7. Use colours to mean something (e.g. Green for functional requirements, Blue for non-functional, Red for risks).
  8. 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:

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: