Diagram Notes Agent Guide

Create and share rich annotated Mermaid diagrams: a Mermaid diagram plus positioned hotspot dots that reveal a hover label/description and a click-to-expand markdown deep-dive panel.

Web UI: https://diagramnotes.com
API base: https://diagramnotes.com/api
An API key is required to create or update diagrams programmatically.

Creating a Diagram

Persistent diagrams with positioned hotspot dots, hover labels, and click-to-expand deep-dive panels. Use for architecture docs, refactor plans, detailed explanations, and multi-diagram pages. Only the creator can update hotspot positions.

Authentication

# Get an API key (one-time setup)
curl -s -X POST https://authreturn.com/api/apps/diagram-notes/api-key \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'
# Returns: {"api_key": "ar_..."}

All authenticated requests use header: X-API-Key: <your-api-key>

Create Annotated Diagram

POST https://diagramnotes.com/api/annotated-diagrams

Request body:

{
    "diagram_id": "project-topic-view",
    "title": "Human-Readable Title",
    "project_name": "project-name",
    "diagram": "flowchart TD\n    A[Node A] --> B[Node B]",
    "hotspots": [
        {
            "id": "hs_1",
            "label": "Short Label",
            "description": "What this does and why it matters",
            "detail": "## Deep Dive\n\nMarkdown content with:\n- Code refs: `backend/server.py:45`\n- File paths\n- Rationale\n- Action items",
            "target": "A"
        }
    ]
}

Key fields:

diagram_id (optional): Human-readable slug. Auto-generated UUID if omitted. Use {project}-{topic}[-{view}] convention.
diagram (required): Mermaid diagram source
hotspots (required): Array of annotation dots, each anchored to a diagram node (see Hotspot Schema below)
title (optional): Display title above diagram
project_name (optional): For organization
documents (optional): Bottom-of-page supporting-documents footnotes — an array of {label, url, note?}. Rendered as a numbered list of external links under the diagram. Use for linking out to the live source of truth (a page, a spec, a doc) instead of pasting copies into hotspots. Only http(s) URLs are accepted.

"documents": [
    {"label": "Prompt: project_revenue", "url": "http://finance:8949/prompts/dcf.project_revenue", "note": "raw template + filled runs"},
    {"label": "Living spec", "url": "https://diagramnotes.com/view?id=other-diagram"}
]

Response (201):

{
    "diagram_id": "project-topic-view",
    "view_url": "https://diagramnotes.com/view?id=project-topic-view",
    "title": "Human-Readable Title"
}

The creating user becomes the owner — only they can update hotspot positions via the viewer or API.

Update Hotspots

PUT https://diagramnotes.com/api/hotspots/{diagram_id}

Body: {"hotspots": [...]} with X-API-Key header. Only the diagram owner can update hotspots — non-owners get 403.

Update Supporting Documents

PUT https://diagramnotes.com/api/annotated_diagram/{diagram_id}/documents

Body: {"documents": [{label, url, note?}, ...]} with X-API-Key header. Replaces the footnote list (owner only). Lets you add/curate the bottom-of-page links on an existing diagram without recreating it.

Retrieve (Public)

GET https://www.brightwrapper.com/api/annotated_diagram/{diagram_id}

No auth required. The raw diagram data is served from BrightWrapper.

Share URL

After creating, share the view_url from the response:

https://diagramnotes.com/view?id={diagram_id}

Progressive Disclosure: 3 Layers

The diagram replaces paragraphs of explanation by encoding information at three depth levels:

Layer 1 — The Diagram Itself

"Shape of the system in 2 seconds."

4-10 nodes (more = clutter, fewer = not worth a diagram)
Every arrow labeled with protocol, data, condition, or timing
Subgraphs for logical grouping
Emojis on key nodes for instant recognition

Layer 2 — Hover (label + description)

"What does this component do?"

label: 2-4 word name (don't restate the node label)
description: 1-2 sentences answering "what and why"
Should add information the diagram can't show (constraints, security properties, performance notes)

Layer 3 — Click (detail field)

"Deep dive with code references."

detail: Full markdown content shown in sidebar on click
Include: file paths, line numbers, code snippets, rationale, tradeoffs, action items
Can include images via ![alt](url) for screenshots
This is where the real depth lives — equivalent to 2-3 paragraphs of documentation

Key principle: Each layer adds NEW information. Never restate what the previous layer already shows.

Hotspot Schema

{
    "id": "hs_1",
    "label": "Short Hover Label",
    "description": "1-2 sentence explanation of what this does and why",
    "detail": "## Markdown Deep Dive\n\nFull explanation with:\n- `file/path.py:42` references\n- Code blocks\n- Rationale",
    "target": "NodeId",
    "doc": 2
}

target (required): the Mermaid element this hotspot annotates, named by its id from the diagram source (not the display label). The dot is placed where the layout algorithm renders that element, so you never supply coordinates and the dot always lands on it. What a target resolves to, per diagram type:
- flowchart — a node id (A in A[Start]) or subgraph id (subgraph CUR[...])
- stateDiagram-v2 — a state id (Running)
- sequenceDiagram — a participant id (F in participant F as Frontend — the id, not the alias), or a message arrow named by its label text (POST /api/login)
doc (optional): footnote cross-reference to the bottom supporting documents list — a 1-based index, or an array of them (2 or [2,3,4]). The dot then displays that number (a single 2, a list 2,5, or a contiguous range 2–4) so a reader can match the dot to its document entry. Pair it with a documents entry at the diagram level.
All hotspots are draggable by the viewer to fine-tune placement.
Aim for 4-8 hotspots per diagram.

Visual Enhancement Techniques

Mermaid Node Shapes

[square brackets]    → component / service
{curly braces}       → decision point
[(cylinder)]         → database / storage
([stadium])          → user action / trigger
[[subroutine]]       → shared utility
((circle))           → event / signal

classDef Colors

classDef frontend fill:#1e3a5f,stroke:#4a90d9,color:#fff
classDef backend fill:#1a3d2e,stroke:#4caf50,color:#fff
classDef data fill:#3d1a2e,stroke:#e91e63,color:#fff
classDef external fill:#3d3a1a,stroke:#ff9800,color:#fff
classDef highlight fill:#4a1a5f,stroke:#9c27b0,color:#fff

Apply with: class NodeId frontend

Arrow Labels — Always Label

A -->|"POST /api/data"| B
B -->|"JWT token"| C
C -->|"SELECT * WHERE..."| D
D -.->|"cache miss"| E

Label types: protocol, data shape, condition, timing, error path.

Diagram Types by Use Case

Use Case	Mermaid Type	Example
Architecture, components	`flowchart TD`	System overviews, data flow
Request flows, interactions	`sequenceDiagram`	API call chains, auth flows
Pipelines, left-to-right flows	`flowchart LR`	CI/CD, data pipelines
State machines	`stateDiagram-v2`	Order lifecycle, connection states
Class relationships	`classDiagram`	Domain models

Naming Convention

{project}-{topic}[-{view}]

Examples:

myapp-submission-flow
auth-return-login-sequence
bright-wrapper-architecture-overview
myapp-refactor-before
myapp-refactor-after

Complete Workflow: Rich Annotated Diagram

Step 1: Create the diagram

curl -s -X POST https://diagramnotes.com/api/annotated-diagrams \
  -H "X-API-Key: ar_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "diagram_id": "myapp-auth-flow",
    "title": "Authentication Flow",
    "project_name": "myapp",
    "diagram": "flowchart TD\n    U[User] -->|enter credentials| F[Frontend]\n    F -->|POST /api/login| B[Backend]\n    B -->|validate user| D[(Database)]\n    D -->|user record| B\n    B -->|JWT token| F\n    F -->|logged in| U",
    "hotspots": [
        {
            "id": "hs_1",
            "label": "Credential Validation",
            "description": "bcrypt hash comparison — timing-safe to prevent side-channel attacks.",
            "detail": "## Auth Details\n\nPassword hashing uses bcrypt with cost factor 12.\n\n- File: `backend/auth.py:45`\n- Passwords never stored in plaintext\n- Failed attempts rate-limited to 5/min per IP",
            "target": "B"
        },
        {
            "id": "hs_2",
            "label": "JWT Structure",
            "description": "Token contains user_id and role. 24h expiry, RS256 signed.",
            "detail": "## JWT Payload\n\n```json\n{\n  \"sub\": \"user_123\",\n  \"role\": \"admin\",\n  \"exp\": 1706745600\n}\n```\n\nSigned with RS256 private key.",
            "target": "F"
        }
    ]
}'

Step 2: Share with the user

The response includes view_url:

Here's the authentication flow:
https://diagramnotes.com/view?id=myapp-auth-flow

Hover over the green dots for context, click them for deep dives.

Other Endpoints

GET /api/health

Returns {"status": "ok"}. Public.

GET /api/auth/status?diagram_id=<id>

Returns {"authenticated": bool, "email": "...", "can_edit": bool, "is_admin": bool}. When diagram_id is provided, can_edit reflects ownership — only the diagram creator gets true. Public (returns authenticated: false when signed out).

GET /view?id=<diagram_id>

Renders a BrightWrapper annotated diagram with interactive hotspots. Requires sign-in. Hotspot dragging is enabled only for the diagram owner (checked via the ownership table).

Checklist Before Creating

Right format? Would text be clearer for this? (< 3 components = probably yes)
4-10 nodes? Enough to be useful, few enough to be readable
All arrows labeled? Every arrow should say what flows through it
Emojis on key nodes? For instant visual recognition
4-8 hotspots? Each adds information the diagram can't show
Hover adds info? Labels and descriptions don't just restate node labels
Detail has depth? Code refs, file paths, rationale — the "why" behind the "what"
Shared the viewer URL? Always give the user the clickable link

Pages (Wiki / Explainer Docs)

Alongside diagrams, Diagram Notes stores plain markdown pages — app docs, explainer notes, design rationale. Same API key and ownership rules as diagrams.

Create / update a page

POST https://diagramnotes.com/api/pages        (X-API-Key)
{
  "page_id": "myapp-some-topic",   // optional; slugified from title if omitted
  "title": "Human Title",
  "project_name": "myapp",          // optional, for grouping
  "body": "# Markdown\n\nFull markdown body…",
  "tags": ["arch", "billing"]       // optional
}

Re-POST your own page_id to update; claiming an unowned id is allowed; overwriting another owner is 403. Returns {page_id, view_url, api_url}.

Read / list / delete

GET    https://diagramnotes.com/api/pages/<page_id>      (public)
GET    https://diagramnotes.com/api/pages?project=myapp&tag=arch   (public list)
DELETE https://diagramnotes.com/api/pages/<page_id>      (X-API-Key, owner only)

Unified search (pages + diagrams)

GET https://diagramnotes.com/api/search?q=<query>        (public)

Returns {results: [{type: "page"|"diagram", id, title, project_name, url, snippet}]}. Case-insensitive substring over titles + page bodies + diagram notes.