Diagram Notes Agent Guide

Create, store, and share annotated Mermaid diagrams. Two modes: simple diagrams (text-matched hover tooltips) and rich annotated diagrams (positioned hotspots with deep-dive detail panels).

When to Create a Diagram

Good fit — use a diagram:

Bad fit — just use text:

Rule of thumb: If 3+ components interact, a diagram beats text.

Option 1: Simple Diagrams

Quick ephemeral diagrams with text-matched hover tooltips. Good for one-off explanations. Creating one needs no API key, but the recipient must sign in to view the /d/<id> link (viewing requires an account).

POST /api/diagrams

Store a diagram and get a shareable URL.

Request body:

Field Type Required Description
diagram string Yes Mermaid diagram source (any type: sequence, flowchart, class, state, etc.)
notes object No Map of element labels to tooltip text. Keys are matched against text in the rendered SVG.
title string No Display title shown above the diagram 
curl -s -X POST https://diagramnotes.com/api/diagrams \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Auth Login Flow",
    "diagram": "sequenceDiagram\n    participant U as User\n    participant F as Frontend\n    participant B as Backend\n    U->>F: Enter credentials\n    F->>B: POST /login\n    B-->>F: JWT token\n    F-->>U: Logged in",
    "notes": {
      "User": "The person logging into the app",
      "Frontend": "Browser-side JS handling the login form",
      "Backend": "Server that validates credentials and issues JWTs",
      "POST /login": "Sends credentials over HTTPS",
      "JWT token": "Signed token used for subsequent API calls"
    }
  }'

Response (201):

{
  "url": "https://diagramnotes.com/d/Ab3xK9mQ",
  "id": "Ab3xK9mQ"
}

Share the url with the user. Diagrams auto-expire after 30 days.

How Notes Work

Notes are matched by text content in the rendered SVG. Keys in notes are matched against text/tspan elements and actor box labels. Matching is substring-based — use descriptive labels to avoid broad matches.

{
  "notes": {
    "User": "Tooltip for the User participant",
    "POST /login": "Tooltip for this arrow label",
    "JWT token": "Tooltip for this response arrow"
  }
}

Embedding Component

Render annotated diagrams inline on any page — no storage needed:

<script src="https://diagramnotes.com/static/diagram-notes.js"></script>
<div id="my-diagram"></div>
<script>
  DiagramNotes.render({
    container: 'my-diagram',
    diagram: `flowchart LR
        A[Input] --> B[Process] --> C[Output]`,
    notes: {
      'Input': 'Raw data from the API',
      'Process': 'Validation and transformation',
      'Output': 'Cleaned result returned to caller'
    }
  });
</script>

Option 2: Rich Annotated Diagrams (Auth Required)

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

Authentication

Sign up for an account at https://diagramnotes.com, then get an API key:

# 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",
            "x": 50,
            "y": 30
        }
    ]
}

Key fields:

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.

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

Layer 2 — Hover (label + description)

"What does this component do?"

Layer 3 — Click (detail field)

"Deep dive with code references."

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",
    "x": 50,
    "y": 30
}

Positioning Heuristics (x/y fallback only)

Only relevant when you can't use target (e.g. placing a dot on an arrow midpoint rather than a node).

flowchart TD (top-down):

flowchart LR (left-right):

sequenceDiagram:

Subgraphs: Place hotspot near the subgraph label, slightly inside.

Visual Enhancement Techniques

Emojis in Node Labels

Consistent mapping for instant recognition:

Emoji Meaning
🌐 Frontend / browser
📦 Server / backend
🔒 Auth / security
🗄️ Database
⚡ Cache / fast path
🔌 External API
👤 User
📨 Message queue
🔍 Search
⚙️ Config / settings
📊 Analytics

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

Common Patterns

1. Architecture Overview

Single flowchart with subgraphs, classDefs, and 6-8 hotspots covering "why this component exists" and "what constraint drives this design."

2. Refactor Plan (Before/After)

Two diagrams on one page:

3. Request Flow Debugging

Sequence diagram with alt blocks for error paths. Hotspots on each participant explaining their role, and on key arrows explaining the data format or protocol.

4. Dependency Map

Flowchart showing module/service dependencies. Hotspots on high-coupling nodes explaining why they're coupled and how to reduce it.

Naming Convention

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

Examples:

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": "sequenceDiagram\n    participant U as 👤 User\n    participant F as 🌐 Frontend\n    participant B as 📦 Backend\n    participant D as 🗄️ Database\n\n    U->>F: Enter credentials\n    F->>B: POST /api/login\n    B->>D: Validate user\n    D-->>B: User record\n    B-->>F: JWT token\n    F-->>U: Logged in",
    "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",
            "x": 55,
            "y": 40
        },
        {
            "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.",
            "x": 55,
            "y": 65
        }
    ]
}'

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 /d/<id>

HTML page rendering a stored simple diagram. Requires sign-in — the page gates on login and fetches the content from /api/diagrams/<id> (so the diagram isn't in the page source for signed-out visitors). Returns 404 if expired or not found.

GET /api/diagrams/<id>

Returns {"id", "title", "diagram", "notes"} for a stored simple diagram. Auth required (X-API-Key or Authorization: Bearer). 404 if not found. Backs the /d/<id> page.

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

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