---
name: whiteboard-board-code
description: Write Whiteboard+ board code, a Mermaid-like text format that builds a whole Confluence whiteboard (sections, sticky notes, Jira cards, links, Mermaid diagrams, connections and step-by-step flows). Use when asked for a whiteboard, a system design, an architecture or design diagram, a retro or planning board for Whiteboard+, or "board code".
---

# Whiteboard+ board code

When the user wants a whiteboard, system design or design diagram for Whiteboard+ (Confluence), answer with
**board code** in one fenced code block and nothing inside the block but the code. The user pastes it onto a
board (or Insert → Board from code) and the board lays itself out. Never give positions or sizes.

**Inside that block, never write ``` again.** A ``` inside it ends the block early in every chat app (ChatGPT,
Claude, Gemini), and what follows is shown as pictures: copying it then loses the diagrams. So write each
diagram as its first line (`flowchart LR`, `sequenceDiagram`, `erDiagram`…) with its lines indented under it,
and each API with its request and response as an `http` line with the raw HTTP indented under it. Don't put
any words before or after the block either.

Wrong (breaks in a chat):

    section "System" track=system
      ```mermaid
      flowchart LR
        App --> API
      ```

Right:

    section "System" track=system
      flowchart LR
        App --> API

**Check before you send:** your whole answer has exactly two lines with ``` in them, the first and the last.
If it has more, rewrite those diagrams and APIs in the indented form above.

Before answering, check the code against the rules below: every alias used in a `flow` or `connect` is
defined with `as`, every string is in double quotes, tracks and colours are from the lists.

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`, `section` or `folder` is 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 `section` line goes in that section, until the next `section`.
- Text goes in double quotes. Inside quotes, `\n` is a new line and `\"` is a quote.
- `as name` gives something an **alias**, so connections and flows can refer to it. An alias uses letters,
  digits, `-` and `_`, and each alias is used once.
- `key=value` settings 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` |
| `http [as alias]` with raw HTTP indented under it | An API card with its req and res filled in | see below |
| a Mermaid diagram | An editable diagram (see below) | `flowchart LR`, its lines indented under it |
| `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 a `folder` line before several sections).
- `step=N` is 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 under an `http` line, indented: 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. (In a file, not a chat, a ```` ```http ```` … ```` ``` ```` block works too.)

```
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 becomes shapes you can move and edit. Write its first line, and its lines indented under it:

```
section "Data" track=data
  erDiagram
    USER ||--o{ LINK : owns
    LINK ||--o{ CLICK : gets
```

To give a diagram an alias or its own look, put it under a `mermaid [as alias] [style=mermaid]` line, indented.

Diagrams are drawn in Excalidraw's hand-drawn style. For Mermaid's look instead, add `style=mermaid` to the
board (`board "Title" style=mermaid`) or to the diagram's `mermaid` line. (In a file, not a chat, a diagram can also be in a ```` ```mermaid ````
block, with its own `style=mermaid` or `style=sketch`.) (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'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)

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` line with the request
   and response indented under it for the important ones, `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 and no ``` inside it.
9. Emoji make a board easier to scan: one at the start of a section's name or a note is fine.

## Full example: a URL shortener

The example is at [url-shortener.txt](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" }
  http as api_get
    # Redirect
    GET /{code}

    HTTP/1.1 302 Found
    Location: https://example.com/a/very/long/page
  http as api_stats
    # 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
```
