# Whiteboard+ board code

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.

> **AI agents answering in a chat:** put the whole board in one code block, and never write ``` inside it. A
> ``` inside a chat answer ends the block early, and the diagrams are lost when it's copied. 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 [as alias]` line with the raw HTTP indented under it. The
> fenced forms below are for code in files.

## 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` |
| 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 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 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)

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](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
  ```mermaid
  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
  ```mermaid
  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
  ```mermaid
  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
  ```mermaid
  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
  ```mermaid
  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): https://migratly.dev/whiteboard/board-code/SKILL.md
- This page as Markdown, for any agent: https://migratly.dev/whiteboard/board-code.md

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.md` in a folder named `whiteboard-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 …".
