DDR for agents: MCP, skills and strict syntax

Machine-oriented DDR guide: MCP server setup and tools, a downloadable SKILL.md, a strict grammar for every diagram type, diagnostic codes with fixes, and do/don't rules.

Generated from the DDR engine 0.0.5-alpha.5 (docs/spec, core/ddr/diag.go, internal/server, docs/examples) by go run ./cmd/ddr-docs. Do not edit by hand.

Human-friendly reference: /docs/syntax.md · This file is also served as /llms.txt and /docs/agents.md.

Rules

Workflow: get_syntax → write the source → check until ok is true (no errors, no warnings) → format → render.

Do

• Start every .ddr file with Type: and Title: lines, then a blank line.
• Use exactly the Type: values in the type list; use Type: Graph for architecture diagrams.
• Declare every node before an edge or goto names it, and give nodes you reference an explicit id (pay: Enter payment).
• Indent with spaces (two per level). One statement per line.
• Quote labels that contain ;, {, }, [, -> or start with a keyword.
• Run check after every edit and fix every error and warning before you answer.
• Run format (or ddr fmt -w) to normalize the file; it never reorders statements.

Don't

• Don't invent types (Sequence, Class, Architecture and UserStory are not types).
• Don't use tabs (W101) or Markdown fences inside a .ddr file.
• Don't add [x, y] or [via: …] unless the user asked for fixed positions; auto layout is better.
• Don't write [x, y] in activities: they are ignored (W110).
• Don't repeat foreign keys in a CDM; the Ref: line is the link.
• Don't put chains (a -> b) inside ERD relations, or -> after a goto.
• Don't use // or trailing comments: only full-line # comments exist.
• Don't run check on a .tdr document (E108); check the .ddr files it embeds.

Diagram types

MCP server

ddr mcp runs a Model Context Protocol server over stdio (newline-delimited JSON-RPC 2.0, protocol 2025-06-18). Install the CLI from the GitHub releases (or go install github.com/Fastering18/ddr/cmd/ddr@latest), then add it to your client.

Cursor (.cursor/mcp.json or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "ddr": { "command": "ddr", "args": ["mcp"] }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ddr": { "command": "/usr/local/bin/ddr", "args": ["mcp"] }
  }
}

Any stdio client: start ddr mcp and write one JSON-RPC message per line:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"check","arguments":{"source":"Type: Flowchart\nTitle: T\n\nFlow {\n  Start\n  End\n}\n"}}}

HTTP clients: the server has no HTTP transport of its own. Run ddr mcp behind any stdio-to-HTTP MCP bridge, or call the same core with the CLI (ddr check, ddr render).

Tools

check

Parse and analyze a .ddr source (a .tdr document gives only E108: check its .ddr files instead). Returns JSON {ok, errors, warnings, diagnostics:[{code,severity,message,line,col}], views:[{kind,name}]}. ok is true only when there are no errors and no warnings.

Input schema:

{
  "additionalProperties": false,
  "properties": {
    "source": {
      "description": "Full text of a .ddr file.",
      "type": "string"
    }
  },
  "required": [
    "source"
  ],
  "type": "object"
}

render

Render a .ddr source to a standalone SVG document. Diagnostics, if any, follow the SVG after a line <!-- diagnostics -->.

Input schema:

{
  "additionalProperties": false,
  "properties": {
    "source": {
      "description": "Full text of a .ddr file.",
      "type": "string"
    },
    "theme": {
      "default": "light",
      "enum": [
        "light",
        "dark"
      ],
      "type": "string"
    },
    "view": {
      "description": "View name from check (default: the first view).",
      "type": "string"
    }
  },
  "required": [
    "source"
  ],
  "type": "object"
}

format

Format a .ddr source like ddr fmt (idempotent, keeps comments, never reorders). Returns the formatted text, or an error listing the syntax errors.

Input schema:

{
  "additionalProperties": false,
  "properties": {
    "source": {
      "description": "Full text of a .ddr file.",
      "type": "string"
    }
  },
  "required": [
    "source"
  ],
  "type": "object"
}

list_types

List every diagram and document type: id, the Type: header value, accepted aliases, file extension, views and a one-line summary.

Input schema:

{
  "additionalProperties": false,
  "properties": {},
  "type": "object"
}

get_syntax

Return the strict DDR syntax guide for agents (Markdown). Pass type (an id from list_types) for just that type's section.

Input schema:

{
  "additionalProperties": false,
  "properties": {
    "type": {
      "description": "Optional type id, e.g. flowchart, erd.",
      "type": "string"
    }
  },
  "type": "object"
}

Skills

Download SKILL.md and put it in your agent's skills folder (for example .cursor/skills/ddr/SKILL.md or ~/.claude/skills/ddr/SKILL.md). It tells the agent when to use DDR, the workflow, the rules and one example per type, and points to the MCP tools when they are available.

Raw Markdown of this page: /docs/agents.md and /llms.txt.

Header keys

The header is Key: value lines at the top of the file, ending at the first blank line. Keys are case-insensitive; unknown keys give W102 and are kept.

Lines, comments and strings

• Comments: a full line starting with #. Order #123 is text, and there are no trailing or // comments. ddr fmt keeps comments; an empty comment stays a bare #.
• Statements: inside { } a statement ends at ; or a newline; the trailing ; is optional. In indented lists, one item per line after - .
• Indentation: spaces only (tabs give W101).
• Colons mean something only after a key at the start of a line (Description:), in an item head (- Customer: Login), and after an id (pay: Enter payment). Anywhere else a colon is text.
• Strings: plain text by default. Quote with "…" when a label contains ;, {, }, [, ->, starts with a keyword, or spans lines. Escapes: \", \\, \n.
• Multiline labels: a quoted label may continue on the next lines; leading blanks up to the statement's column are dropped.

# A comment line
Type: Flowchart
Title: Lexical example

Flow {
  Start
  Read order #123
  note: "Contains; a semicolon"
  End
}

Sections

A section is Name: followed by an indented - list, or Name { … } (a block). Section names are case-insensitive.

Ids, labels and attributes

Every node is id: Label [key: value, flag]. Without an id the id is the slug of the label (Enter payment details → enter-payment-details). Ids match [A-Za-z_][A-Za-z0-9_.-]*. Several attribute groups are allowed: Login [shape: round] [x: 10, y: 20]. Unknown attributes give W105.

Node attributes:

Positions and bends

• [x: 120, y: 80] pins a node's centre (the editor writes it when you drag a node). Nodes without positions get auto layout.
• [via: (220,120) (220,300)] on an edge sets its bend points in order (the editor writes it when you drag a line).
• ERD attributes take [x, y] too. Activities ignore both (W110).

Type: Graph
Title: Pinned

Graph {
  a: Client [x: 100, y: 80]
  b: Server [x: 400, y: 80]
  a -> b: request [via: (250,20)]
}

Edges and chains

Chains. a -> b -> c adds one edge per consecutive pair. A label (: text) and attribute groups belong to the segment they follow; nothing is copied to other segments. Spaces around -> are optional (a->b->c). Every unknown node is E203; nodes are never created by an edge. A targetless -> [..] inside a chain or a trailing -> is ignored with W126. References chain with their own operators: Ref: a.id < b.a_id: owns < c.b_id: keeps.

Edge attributes:

Type: Graph
Title: Chain

Graph {
  a: Browser
  b: API
  c: Database [shape: cylinder]
  a -> b: HTTPS -> c: SQL [dashed]
}

Flow statements

Used in Flowchart, Activity and use case Flow { } blocks. Keywords count only at the start of a statement and are case-insensitive: if, elif, else, loop, goto, Start, End; in activities also parallel … and, stop.

stmt = step | "Start" [label] | "End" [label]
     | "if" cond block { "elif" cond block } [ "else" block ]
     | "loop" [cond] block | "goto" id | id ":" label | edge
     | "parallel" block { "and" block } | "stop" ;   (* activity only *)

• if cond? { … } leaves by Yes into the block and by No past it.
• loop cond? { … } asks before each pass; loop { … } asks Repeat?.
• @Name in a step links it to an actor.
• Line jumps: where two straight lines cross, one hops over the other. Line Jumps: off turns it off.

Diagnostic codes

Every code the engine emits (read from core/ddr/diag.go). E codes are errors: the diagram is not drawn correctly. W codes are warnings: drawn, but fix them.

HTTP API

The cloud server's REST API. Paths are under /api/v1 except /healthz, /ws/… and the browser redirects of Google sign-in. JSON in and out; errors are application/problem+json ({"type","title","status","detail"}). Auth is the ddr_session cookie set by login/register; optional means signed-out callers see public projects only. State-changing requests must come from the same origin. Every route below is read from internal/server/server.go; a test fails if one is missing.

Diagrams are rendered in the browser (WebAssembly), by ddr render and by the MCP render tool; the server stores text and has no render endpoint yet.

Health

GET /healthz · auth: none
Liveness probe (outside /api/v1).

Response:

200 {"status":"ok","db":true,"realtime":{…}} (503 "degraded" when the database is down)

GET /api/v1/health · auth: none
Liveness probe.

Response:

200 {"status":"ok","db":true,"realtime":{…}} (503 "degraded" when the database is down)

Admin

GET /api/v1/admin/stats · auth: session
Site statistics (admins only).

Response:

200 {"users":12,"projects":40,"files":180,"storageBytes":123456}

GET /api/v1/admin/users · auth: session
Users with role, project count and last seen (?q= filters).

Response:

200 {"items":[]}

PATCH /api/v1/admin/users/{id} · auth: session
Set a user's site role (user or admin).

Request:

{"role":"admin"}

Response:

200 {"id":"…","role":"admin"}

GET /api/v1/admin/audit · auth: session
Audit log: sign-ins, project/file create/delete, uploads, role changes, agent use (?action=, ?before=, ?limit=).

Response:

200 {"items":[]}

Agent

GET /api/v1/agent/status · auth: session
Which AI providers budi can use and whether you saved your own key.

Response:

200 {"providers":["gemini:gemini-2.5-flash"],"byokEnabled":true,"available":true}

POST /api/v1/agent/chat · auth: session
Chat with budi. context is graph-retrieved project context; edits come back as fenced file blocks for review. Rate limited per user.

Request:

{"messages":[{"role":"user","content":"add a cancel step"}],"context":"…","projectId":"…"}

Response:

200 {"reply":"…","provider":"gemini","model":"gemini-2.5-flash"}

PUT /api/v1/me/agent-key · auth: session
Save your own AI key (encrypted at rest); budi uses it first, then the free providers.

Request:

{"provider":"openrouter","model":"","key":"sk-…"}

Response:

204 No Content

DELETE /api/v1/me/agent-key · auth: session
Remove your own AI key or disconnect OpenRouter.

Response:

204 No Content

POST /api/v1/me/agent-key/openrouter · auth: session
Finish OpenRouter OAuth PKCE: exchanges the code for a key on your OpenRouter account (your credits).

Request:

{"code":"…","codeVerifier":"…","model":"openrouter/auto"}

Response:

204 No Content

Auth

POST /api/v1/auth/register · auth: none
Create an account and sign in (sets the session cookie). Rate limited.

Request:

{"email":"ana@example.com","password":"correct horse battery","name":"Ana"}

Response:

201 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

POST /api/v1/auth/login · auth: none
Sign in with email and password (sets the session cookie). Rate limited.

Request:

{"email":"ana@example.com","password":"correct horse battery"}

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

POST /api/v1/auth/logout · auth: optional
End the current session and clear the cookie.

Response:

204 No Content

POST /api/v1/auth/verify · auth: none
Confirm an email address with the token from the mail.

Request:

{"token":"v_abc…"}

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

POST /api/v1/auth/verify/resend · auth: session
Send a new verification link (valid 24h, single use). At most one per minute and 10 per day per user; otherwise 429 with Retry-After. Mail goes through Resend (RESEND_API_KEY) or SMTP (SMTP_HOST…), from MAIL_FROM; with neither, the link is written to the server log.

Response:

200 {"retryAfter":60,"remainingToday":9,"cooldown":60,"dailyLimit":10}

GET /api/v1/auth/verify/status · auth: session
Whether your email is verified, whether verification is required (EMAIL_VERIFICATION_REQUIRED; when false new emails are verified at once and resend answers 409 verification_disabled), and when Resend is allowed again.

Response:

200 {"verified":false,"required":true,"retryAfter":42,"remainingToday":8,"cooldown":60,"dailyLimit":10}

POST /api/v1/auth/forgot · auth: none
Request a password reset mail. Always 204, so it cannot probe for accounts.

Request:

{"email":"ana@example.com"}

Response:

204 No Content

POST /api/v1/auth/reset · auth: none
Set a new password with the reset token.

Request:

{"token":"r_abc…","password":"new long password"}

Response:

204 No Content

GET /api/v1/auth/oauth/{provider} · auth: none
Generic OAuth route for other providers: always 501. Google sign-in has its own routes (GET /auth/google) once they are on this server.

Response:

501 {"type":"…/not_implemented","status":501,"detail":"…"}

GET /api/v1/auth/oauth/{provider}/callback · auth: none
Callback of the generic OAuth route: always 501.

Response:

501 {"type":"…/not_implemented","status":501,"detail":"…"}

GET /api/v1/auth/providers · auth: none
Which sign-in methods this server offers.

Response:

200 {"password":true,"google":true}

GET /auth/google · auth: none
Start Google sign-in (outside /api/v1). ?next=/path is where to land afterwards (same-site paths only).

Response:

302 Location: https://accounts.google.com/o/oauth2/v2/auth?…

GET /auth/google/callback · auth: none
Google redirects here (outside /api/v1); signs in or creates the account, sets the session cookie.

Request:

`?code=…&state=…`

Response:

302 Location: /<next> (or /login?error=<code>)

Account

GET /api/v1/me · auth: session
The signed-in user.

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

PATCH /api/v1/me · auth: session
Change name, email, language or password. A new password, or a new email on an account with a password, needs currentPassword. A new email starts unverified and gets a verification link; email changes share the resend limits (1 per minute, 10 per day) and are capped at 5 per day (429 with Retry-After).

Request:

{"name":"Ana B.","email":"ana@new.example","currentPassword":"…"}

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

PUT /api/v1/me/avatar · auth: session
Upload an avatar: the raw PNG, JPEG or WebP as the body (max 2 MB). Stored as a 256x256 WebP in S3-compatible storage (S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_FORCE_PATH_STYLE); the previous one is deleted. 422 for other types, 413 when too large.

Request:

<image bytes>

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

DELETE /api/v1/me/avatar · auth: session
Remove the uploaded avatar (a Google profile picture shows again if there is one).

Response:

200 {"id":"7b6c…","email":"ana@example.com","name":"Ana","avatarUrl":null,"emailVerified":true,"createdAt":"2026-10-22T10:00:00Z"}

GET /api/v1/users/{id}/avatar · auth: none
An uploaded avatar (image/webp). With ?v=<etag> it is cached for a year; sends an ETag and answers If-None-Match with 304.

Response:

200 image/webp

GET /api/v1/me/sessions · auth: session
List your sessions.

Response:

200 {"items":[{"id":"…","createdAt":"…","lastSeenAt":"…","expiresAt":"…","userAgent":"Firefox","ip":"203.0.113.5","current":true}]}

DELETE /api/v1/me/sessions/{id} · auth: session
Sign out one session.

Response:

204 No Content

GET /api/v1/me/invites · auth: session
Pending invites for your email.

Response:

200 {"items":[{"id":"c1e2…","projectId":"3f2a…","email":"bo@example.com","role":"editor","status":"pending","createdAt":"…","expiresAt":"…"}],"emailVerified":true}

POST /api/v1/me/invites/{id}/accept · auth: session
Accept an invite addressed to you.

Response:

200 {"projectId":"3f2a…","role":"editor"}

POST /api/v1/me/invites/{id}/decline · auth: session
Decline an invite addressed to you.

Response:

204 No Content

GET /api/v1/me/limits · auth: session
Your site role, usage and quotas.

Response:

200 {"role":"user","usage":{"projects":3,"storageBytes":10240},"limits":{"projects":30,"filesPerProject":30,"fileBytes":2097152,"storageBytes":262144000}}

DELETE /api/v1/me · auth: session
Delete your account.

Response:

204 No Content

GET /api/v1/me/identities · auth: session
Linked sign-in identities (e.g. Google).

Response:

200 {"items":[{"provider":"google","email":"ana@example.com"}]}

DELETE /api/v1/me/identities/{provider} · auth: session
Unlink an identity.

Response:

204 No Content

Projects

GET /api/v1/projects · auth: optional
List projects. ?filter= (all default; public lists public projects signed out), ?limit=, ?offset=.

Response:

200 {"items":[{"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}],"limit":50,"offset":0}

POST /api/v1/projects · auth: session
Create a project.

Request:

{"name":"Online Store","description":"","visibility":"private"}

Response:

201 {"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}

POST /api/v1/projects/import · auth: session
Import a .ddrproj.zip (raw application/zip body or multipart field file). ?name= overrides the name.

Request:

<zip bytes>

Response:

201 {"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}

GET /api/v1/projects/{pid} · auth: optional
One project (members, link holders, or public).

Response:

200 {"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}

PATCH /api/v1/projects/{pid} · auth: session
Rename, describe, change visibility or template flag.

Request:

{"visibility":"public"}

Response:

200 {"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}

DELETE /api/v1/projects/{pid} · auth: session
Delete a project (owner).

Response:

204 No Content

POST /api/v1/projects/{pid}/duplicate · auth: session
Copy a project you can view into your account.

Request:

{"name":"Online Store copy"}

Response:

201 {"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"}

GET /api/v1/projects/{pid}/export.zip · auth: optional
Download the project as .ddrproj.zip.

Response:

200 application/zip

GET /api/v1/p/{slug} · auth: none
A public project and its files by slug.

Response:

200 {"project":{"id":"3f2a…","name":"Online Store","slug":"online-store","description":"","visibility":"private","template":false,"ownerId":"7b6c…","ownerName":"Ana","role":"owner","createdAt":"…","updatedAt":"…"},"files":[{"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}]}

Files

POST /api/v1/projects/{pid}/assets · auth: session
Upload a file (raw body, ?path=img/logo.png): png, jpg, gif, webp, svg, pdf, txt, csv, md. Free accounts: 2 MB per file, 30 files per project, 250 MB in total (403 quota_exceeded).

Response:

201 {"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}

GET /api/v1/projects/{pid}/files/{fid}/raw · auth: optional
The bytes of an uploaded file (sandboxed CSP), for embedding in .tdr documents.

Response:

200 image/png

GET /api/v1/projects/{pid}/files · auth: optional
List files.

Response:

200 {"items":[{"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}]}

POST /api/v1/projects/{pid}/files · auth: session
Create a file (kind ddr or tdr, inferred from the path).

Request:

{"path":"diagrams/flow.ddr","content":"Type: Flowchart\nTitle: Flow\n"}

Response:

201 {"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}

GET /api/v1/projects/{pid}/files/{fid} · auth: optional
File metadata. Sends an ETag.

Response:

200 {"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}

PATCH /api/v1/projects/{pid}/files/{fid} · auth: session
Rename or replace content. Send If-Match or version; a stale version is 412.

Request:

{"path":"diagrams/checkout.ddr","version":1}

Response:

200 {"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}

DELETE /api/v1/projects/{pid}/files/{fid} · auth: session
Delete a file.

Response:

204 No Content

GET /api/v1/projects/{pid}/files/{fid}/text · auth: optional
The file text (text/plain, ETag; If-None-Match gives 304).

Response:

200 text/plain
Type: Flowchart
Title: Flow

PUT /api/v1/projects/{pid}/files/{fid}/text · auth: session
Replace the text (text/plain body). If-Match: "v1"; ?reset=true drops the live Yjs state.

Request:

Type: Flowchart
Title: Flow

Response:

200 {"id":"91d0…","seq":4,"path":"diagrams/flow.ddr","kind":"ddr","version":1,"etag":"\"v1\"","size":64,"createdAt":"…","updatedAt":"…"}

Sharing

GET /api/v1/projects/{pid}/members · auth: session
List members.

Response:

200 {"items":[{"userId":"…","email":"bo@example.com","name":"Bo","avatarUrl":null,"role":"editor","addedAt":"…"}]}

POST /api/v1/projects/{pid}/members · auth: session
Invite by email (same as POST invites).

Request:

{"email":"bo@example.com","role":"editor"}

Response:

201 {"id":"c1e2…","projectId":"3f2a…","email":"bo@example.com","role":"editor","status":"pending","createdAt":"…","expiresAt":"…"}

PATCH /api/v1/projects/{pid}/members/{uid} · auth: session
Change a role; owner transfers ownership.

Request:

{"role":"viewer"}

Response:

200 {"userId":"…","role":"viewer"}

DELETE /api/v1/projects/{pid}/members/{uid} · auth: session
Remove a member (or leave).

Response:

204 No Content

GET /api/v1/projects/{pid}/invites · auth: session
List invites.

Response:

200 {"items":[{"id":"c1e2…","projectId":"3f2a…","email":"bo@example.com","role":"editor","status":"pending","createdAt":"…","expiresAt":"…"}]}

POST /api/v1/projects/{pid}/invites · auth: session
Invite by email.

Request:

{"email":"bo@example.com","role":"editor"}

Response:

201 {"id":"c1e2…","projectId":"3f2a…","email":"bo@example.com","role":"editor","status":"pending","createdAt":"…","expiresAt":"…"}

DELETE /api/v1/invites/{id} · auth: session
Revoke an invite.

Response:

204 No Content

POST /api/v1/invites/{id}/resend · auth: session
Resend an invite mail.

Response:

200 {"id":"c1e2…","projectId":"3f2a…","email":"bo@example.com","role":"editor","status":"pending","createdAt":"…","expiresAt":"…"}

GET /api/v1/invites/lookup · auth: none
Describe an invite by ?token=.

Response:

200 {"projectName":"Online Store","inviterName":"Ana","email":"bo@example.com","role":"editor","status":"pending"}

GET /api/v1/invites/{token} · auth: none
Same as lookup, token in the path.

Response:

200 {"projectName":"Online Store","inviterName":"Ana","email":"bo@example.com","role":"editor","status":"pending"}

POST /api/v1/invites/accept · auth: session
Accept an invite by token.

Request:

{"token":"i_abc…"}

Response:

200 {"projectId":"3f2a…","role":"editor"}

POST /api/v1/invites/decline · auth: none
Decline an invite by token.

Request:

{"token":"i_abc…"}

Response:

204 No Content

GET /api/v1/projects/{pid}/links · auth: session
List share links.

Response:

200 {"items":[{"id":"5aa1…","projectId":"3f2a…","role":"viewer","token":"s_9x…","url":"https://example.com/s/s_9x…","createdAt":"…","expiresAt":null}]}

POST /api/v1/projects/{pid}/links · auth: session
Create a share link. Editor links need confirm: true.

Request:

{"role":"viewer","expiresInHours":72}

Response:

201 {"id":"5aa1…","projectId":"3f2a…","role":"viewer","token":"s_9x…","url":"https://example.com/s/s_9x…","createdAt":"…","expiresAt":null}

DELETE /api/v1/projects/{pid}/links/{lid} · auth: session
Revoke a link.

Response:

204 No Content

DELETE /api/v1/projects/{pid}/links · auth: session
Revoke a link given as ?id=.

Response:

204 No Content

GET /api/v1/links/lookup · auth: none
Describe a share link by ?token=.

Response:

200 {"projectId":"3f2a…","projectName":"Online Store","role":"viewer","expiresAt":null}

POST /api/v1/links/accept · auth: session
Join a project through a share link.

Request:

{"token":"s_9x…"}

Response:

200 {"projectId":"3f2a…","role":"viewer"}

GET /api/v1/projects/{pid}/access-requests · auth: session
List access requests (managers).

Response:

200 {"items":[{"id":"e4f5…","projectId":"3f2a…","userId":"8c9d…","message":"May I view this?","status":"pending","createdAt":"…"}]}

POST /api/v1/projects/{pid}/access-requests · auth: session
Ask the owner for access.

Request:

{"message":"May I view this?"}

Response:

201 {"id":"e4f5…","projectId":"3f2a…","userId":"8c9d…","message":"May I view this?","status":"pending","createdAt":"…"}

PATCH /api/v1/access-requests/{id} · auth: session
Approve or deny a request.

Request:

{"status":"approved","role":"viewer"}

Response:

200 {"id":"e4f5…","projectId":"3f2a…","userId":"8c9d…","message":"May I view this?","status":"pending","createdAt":"…"}

Planned

GET /api/v1/assets/{aid} · auth: optional
Read an asset (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

GET /api/v1/projects/{pid}/versions · auth: session
Version history (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

POST /api/v1/projects/{pid}/versions · auth: session
Save a version (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

POST /api/v1/projects/{pid}/versions/{vid}/restore · auth: session
Restore a version (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

GET /api/v1/files/{fid}/threads · auth: session
Comment threads (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

POST /api/v1/files/{fid}/threads · auth: session
Start a thread (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

POST /api/v1/threads/{tid}/comments · auth: session
Reply (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

PATCH /api/v1/threads/{tid} · auth: session
Resolve a thread (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

POST /api/v1/projects/{pid}/export · auth: session
Server-side render/export job (planned). Today rendering runs in the browser (WebAssembly), the ddr render CLI and the render MCP tool.

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

GET /api/v1/exports/{id} · auth: session
Export job status (planned).

Response:

501 {"type":"…/not_implemented","title":"Not Implemented","status":501,"detail":"not available in v0.0.1"}

Realtime

GET /ws/projects/{pid} · auth: session
WebSocket for live editing (outside /api/v1). Binary frames kind u8 | docRef uvarint | payload: 0x01 subscribe to file (docRef = file seq), 0x02 unsubscribe, 0x10 y-protocols sync, 0x11 awareness, 0x12 checkpoint, 0x13 seq ack, 0x20 file tree (JSON), 0x30 presence (JSON), 0x40 events (JSON), 0x7E error, 0x7F ping.

Request:

GET with `Upgrade: websocket` and the session cookie

Response:

101 Switching Protocols

Flowchart

Classic flowchart (ISO 5807): terminators, process boxes, decision diamonds, input/output parallelograms.

• Header: Type: Flowchart
• Accepted Type: values (case-insensitive): flowchart, flow
• File: .ddr
• Views: flow

Grammar:

file      = header blank "Flow" "{" { stmt } "}" ;
stmt      = step | start | end | if | loop | goto | edge ;
start     = "Start" [ label ] ;
end       = "End" [ label ] ;
step      = [ id ":" ] label { attrs } [ "->" ( attrs | target [ ":" label ] { attrs } ) ] ;
if        = "if" cond [ "->" attrs [ "->" attrs ] ] block { "elif" cond block } [ "else" block ] ;
loop      = "loop" [ cond ] block ;
goto      = "goto" id [ attrs ] ;
edge      = id "->" id [ ":" label ] { attrs } { "->" id [ ":" label ] { attrs } } ;
block     = "{" { stmt } "}" ;

• Write one Flow { } block. Statements end at a newline or ;.
• Start and End are rounded terminators. Write End once, as the last statement: every branch that finishes flows into it (a later End with a different label gives W128 once that check lands).
• if cond? { … } else { … } draws a diamond with Yes / No exits. Rename them with clauses: if ok? -> [label: Accepted] -> [label: Rejected] { … }.
• loop cond? { … } repeats the block while the condition holds; loop { … } asks Repeat?.
• goto id jumps to the step with that id (id: Label declares one).
• A step whose first word is Input, Output, Read, Print, Display, Show, Enter or Prompt is drawn as a parallelogram; [shape: rect] turns that off for one step.
• @Name in a step links it to an actor (inside use cases).

Example (docs/examples/flowchart.ddr):

Type: Flowchart
Title: Password reset
Direction: TB

# One Flow block. Steps run top to bottom; `if`, `loop` and `goto` branch.
Flow {
  Start;
  Enter email address;
  if Account exists? {
    Send reset link;
    open: Open link from email;
    if Link still valid? {
      Choose new password;
    } else {
      Show expired message;
      goto open;
    }
  } else {
    Show generic confirmation;
  }
  End;
}

Flowchart: Start/End labels and the one End

start = "Start" [ ":" ] [ label ] ;
end   = "End" [ ":" ] [ label ] ;

• Start: Order received and Start Order received are the same: the label of the start terminator. End: label likewise.
• A flowchart or graph draws one End. Every End (an early exit inside an if, the end of an else, the last statement) routes its own arrow into the first End written.
• A later End with a different label still joins that End, but its label is not drawn: W128. Give every End the same label, or none.

Example (docs/examples/pending/flowchart-start-end-labels.ddr):

Type: Flowchart
Title: Order approval

Flow {
  Start: Order received;
  if In stock? {
    Ship order;
    End: Order closed;
  } else {
    Notify customer;
    End: Order closed;
  }
}

Graph

Free boxes-and-arrows graph: node statements and explicit a -> b edges.

• Header: Type: Graph
• File: .ddr
• Views: graph

Grammar:

file  = header blank ( "Graph" | "Nodes" ) "{" { node | edge } "}" [ "Edges" "{" { edge } "}" ] ;
node  = [ id ":" ] label { attrs } ;
edge  = id "->" id [ ":" label ] { attrs } { "->" id [ ":" label ] { attrs } } ;

• Declare nodes as id: Label [attrs]; edges name ids: api -> db: SQL.
• Edges never create nodes: an unknown id is E203.
• Use shape, color and [style: curve] / [dashed] to style.

Example (docs/examples/graph.ddr):

Type: Graph
Title: Order service
Direction: LR

Graph {
  user: Customer [shape: actor];
  web: Web app [shape: round];
  api: Order API;
  queue: Event queue [shape: pill, color: amber];
  db: Orders database [shape: cylinder];
  mail: Email service [shape: round, color: teal];
  user -> web: browses;
  web -> api: JSON over HTTPS;
  api -> db: SQL;
  api -> queue -> mail: order.created;
}

Architecture

Architecture diagrams are written as Type: Graph with shapes (cylinder for stores, actor for people, round for services) and colors per tier.

• Header: Type: Graph
• File: .ddr
• Views: graph

Grammar:

Same as Graph.

• There is no separate Type: Architecture; it gives W107. Write Type: Graph.
• Suggested shapes: actor people, round / pill services, cylinder databases and queues, box external systems.
• Use Direction: LR for left-to-right tiers and [dashed] for asynchronous calls.

Example (docs/examples/architecture.ddr):

Type: Graph
Title: Web platform architecture
Direction: LR

# Architecture diagrams are Graphs with shapes and colors for each tier.
Graph {
  browser: Browser [shape: round];
  cdn: CDN [shape: pill, color: teal];
  app: App server;
  worker: Background worker [color: purple];
  cache: Cache [shape: cylinder, color: red];
  db: Database [shape: cylinder];
  store: File storage [shape: cylinder, color: amber];
  browser -> cdn: static files;
  browser -> app: API calls;
  app -> cache;
  app -> db: reads and writes;
  app -> worker: jobs [dashed];
  worker -> store: uploads;
}

Use case

UML use case diagram: actors outside a system boundary, use cases inside, include / extend / generalization.

• Header: Type: UseCase
• Accepted Type: values (case-insensitive): usecase, use case
• File: .ddr
• Views: overview, plus flow: <use case> per use case with a Flow

Grammar:

file      = header blank "Actors:" { actor } "Use Cases:" { case | group } ;
actor     = "-" name { attrs } [ "->" name "[head: triangle]" ] ;
case      = "-" actors ":" name { attrs } [ "->" actor { attrs } ] { field } ;
group     = "-" actors [ ":" ] "{" { name { attrs } [ "{" fields "}" ] ( ";" | NL ) } "}" ;
actors    = name { "," name } ;
field     = key ":" text | ( "Flow" | "Main Flow" | "Alternative" [ N ] | "Exceptions" ) "{" { stmt } "}" ;
key       = "Description" | "Includes" | "Extends" | "Precondition" | "Postcondition" | "Actors" | ... ;

• Fields of a case (indented under it): Description, Includes, Extends, Precondition, Postcondition, Flow { }, Main Flow { }, Alternative N { }, Exceptions { }.
• Includes: A, B draws dashed «include» arrows; Extends: Base draws «extend» toward the base.
• Generalization: - Child -> Parent [head: triangle] under Actors or Use Cases.
• Group cases that share actors: - Customer { Browse; Search }.
• [code: UC07] sets a code by hand; [spec: none] leaves a case out of spec tables.
• Specification keys also have Indonesian aliases (Deskripsi, Alur Dasar, Alur Alternatif N, Kebutuhan Spesifik, …) for teams that write specs in Indonesian.

Example (docs/examples/usecase.ddr):

Type: UseCase
Title: Online Store
Author: Product Team

Actors:
- Customer
- Store Manager
- Payment Provider [system]

Use Cases:
- Customer: Browse catalog
  Description: The customer looks through products by category.
- Customer: Place order
  Description: The customer buys the items in the cart.
  Includes: Pay for order
- Customer, Payment Provider: Pay for order
  Description: The order total is charged to the customer.
- Customer: Track order
  Extends: Place order
- Store Manager: Manage products
  Description: The manager adds, edits and removes products.

Activity

UML activity diagram with swimlanes, decisions, merges, fork/join bars and one implicit start and end.

• Header: Type: Activity
• Accepted Type: values (case-insensitive): activity, activity diagram
• File: .ddr
• Views: activity

Grammar:

file      = header blank ( "Flow" | "Activity" ) "{" { stmt } "}" ;
stmt      = [ lane ":" ] ( step | if | loop | parallel | goto | "start" | "end" | "stop" | edge ) ;
step      = [ id ":" ] label { attrs } ;
if        = "if" cond [ "[yes:" text "," "no:" text "]" ] block { "elif" cond block } [ "else" block ] ;
loop      = "loop" [ cond ] block ;
parallel  = "parallel" block "and" block { "and" block } ;

• Lane: step puts a statement in a lane; a statement without a prefix stays in the previous lane.
• Start and end are implicit: one initial node before the first statement and one activity final after the last. end / stop in a branch routes into that same final.
• parallel { … } and { … } draws a fork bar and a join bar.
• Layout is automatic: [x, y] and [via: …] are ignored (W110).

Example (docs/examples/activity.ddr):

Type: Activity
Title: Support ticket
Lanes: Customer, Support, System

Flow {
  Customer: Submit ticket
  System: Assign ticket number
  Support: Review ticket
  if Needs more information? {
    Support: Ask customer for details
    Customer: Reply with details
  } else {
    Support: Accept ticket
  }
  parallel {
    Support: Resolve issue
  } and {
    System: Notify customer of progress
  }
  Customer: Confirm resolution
}

Language of generated labels (Lang)

lang = ( "Lang" | "Language" ) ":" ( "en" | "id" ) ;

• One header line sets the language of every generated label: activity guards ([Yes] / [No] or [Ya] / [Tidak], Repeat? / Ulangi?) and use case specification labels and step text.
• Without a Lang: line the language is English (en).
• Any other value gives W129 and the default is used.
• Guards you write yourself ([yes: valid, no: invalid]) are never translated.

Example (docs/examples/pending/activity-lang.ddr):

Type: Activity
Title: Leave request
Lang: en
Lanes: Employee, Manager

Flow {
  Employee: Submit leave request
  Manager: Review request
  if Approved? {
    Manager: Record approval
  } else {
    Employee: Revise request
  }
}

Conceptual data model (CDM)

PowerDesigner-style conceptual model: entities, attributes with identifiers <pi> and mandatory <M>, named relationships with crow's feet.

• Header: Type: CDM
• Accepted Type: values (case-insensitive): cdm, conceptual, conceptual data model
• File: .ddr
• Views: cdm

Grammar:

file      = header blank "Entities:" { entity } { ref } ;
entity    = "-" name ( "{" attr { ( ";" | NL ) attr } "}" | NL { INDENT attr NL } ) ;
attr      = name [ ":" type ] { attrs } ;           (* [identifier] [pi] [mandatory] [M] *)
ref       = "Ref:" end op end [ ":" name ] { attrs } { op end [ ":" name ] } ;
end       = entity_name [ "." attr_name ] ;
op        = "<" | ">" | "-" | "<>" ;

• < one-to-many, > many-to-one, - one-to-one, <> many-to-many.
• [identifier] (or [pi]) marks <pi> and <M>; [mandatory] / [M] marks only <M>.
• SQL-ish types are shown conceptually: varchar(100) → Variable characters (100), int → Integer, double → Long float.
• Do not repeat foreign keys in a CDM: Ref: Customer < Order is the link.
• Unnamed relationships are labeled Relationship_1, Relationship_2, …

Example (docs/examples/cdm.ddr):

Type: CDM
Title: Online Store

Entities:
- Customer {
    Customer ID: varchar(12) [identifier]
    Full Name: varchar(80) [mandatory]
    Email: varchar(120)
  }
- Order {
    Order ID: varchar(12) [identifier]
    Order Date: date [mandatory]
    Total: double
  }
- Product {
    Product ID: varchar(12) [identifier]
    Name: varchar(100) [mandatory]
    Price: double
  }

Ref: Customer < Order: places
Ref: Order <> Product: contains

Physical data model (PDM)

Physical tables with SQL types and PK/FK columns; references are written between columns.

• Header: Type: PDM
• Accepted Type: values (case-insensitive): pdm, physical, physical data model
• File: .ddr
• Views: pdm

Grammar:

file      = header blank ( "Tables:" | "Entities:" ) { table } { ref } ;
table     = "-" name ( "{" column { ( ";" | NL ) column } "}" | NL { INDENT column NL } ) ;
column    = name ":" sqltype { attrs } ;             (* [pk] [fk] [unique] [not null] [null] *)
ref       = "Ref:" table "." column op table "." column [ ":" name ] { attrs } ;

• Mark primary keys with [pk]; a column on the many side of a Ref: is shown as FK automatically.
• [not null], [null], [unique] are accepted and kept.
• Attributes on a ref line go last: Ref: a.id < b.a_id: owns [via: (420,80)].

Example (docs/examples/pdm.ddr):

Type: PDM
Title: Online Store

Tables:
- customers {
    customer_id: bigint [pk]
    full_name: varchar(120) [not null]
    email: varchar(180) [not null]
  }
- orders {
    order_id: bigint [pk]
    customer_id: bigint [not null]
    ordered_at: timestamp [not null]
  }
- order_items {
    order_id: bigint [pk]
    product_id: bigint [pk]
    quantity: int [not null]
  }
- products {
    product_id: bigint [pk]
    name: varchar(100) [not null]
    price: numeric(10,2) [not null]
  }

Ref: customers.customer_id < orders.customer_id
Ref: orders.order_id < order_items.order_id
Ref: products.product_id < order_items.product_id

Entity relationship (ERD, Chen)

Chen notation: entities are rectangles, relations diamonds, attributes ovals; key * (bold, underlined), foreign key **, derived # (dashed), composite name { ... }.

• Header: Type: ERD
• Accepted Type: values (case-insensitive): erd, er, entity relationship, chen
• File: .ddr
• Views: erd

Grammar:

file      = header blank "Entities:" { entity } "Relations:" { relation } ;
entity    = "-" name "{" attr { ";" attr } "}" ;
attr      = mark name [ "[x:" n "," "y:" n "]" ] [ "{" attr { ";" attr } "}" ]
          | name [ "*" | "**" ] [ "#" ] [ "[x:" n "," "y:" n "]" ] [ "{" attr { ";" attr } "}" ] ;
mark      = "*" | "**" ;
relation  = "-" name "{" member { ";" member } "}" ;
member    = entity_name [ ":" card ] | attr ;          (* card: 1, M, N, 0..1, ... *)

• Name * is a key attribute, drawn bold and underlined with no star; *Name also works.
• Name ** is a foreign key: accepted and kept, drawn as a plain attribute for now.
• Name # is a derived attribute, drawn with a dashed outline. Only a trailing # counts; a line that starts with # is still a comment.
• Name { A; B } is a composite attribute: A and B hang off Name, and they may nest again.
• In a relation, a line naming an entity joins it; Entity: card also prints the cardinality.
• Any other line in a relation is an attribute of the relation.
• A relation may join three or more entities; a self relation names the same entity twice.
• Do not write chains (A -> B) inside a relation (W124).

Example (docs/examples/erd.ddr):

Type: ERD
Title: Online Store

Entities:
- Customer { Customer ID *; Name; Email }
- Order { Order ID *; Order Date; Customer ID ** }
- Product { Product ID *; Name; Price }

Relations:
- Places { Customer: 1; Order: N }
- Contains { Order: M; Product: N; Quantity }

ERD: ternary relationships

A relation joins every entity it names, so a ternary (or wider) relationship is one diamond with three member lines:

relation = "-" name "{" member ";" member ";" member { ";" ( member | attr ) } "}" ;

• Each entity gets its own line from the diamond, with its cardinality beside the entity.
• Lines that are not entity names (Term) are attributes of the relation.
• A relation naming fewer than two entities gives W124.

Example (docs/examples/erd-ternary.ddr):

Type: ERD
Title: Course enrollment

Entities:
- Student { Student ID *; Name }
- Course { Course ID *; Title }
- Teacher { Teacher ID *; Name }

Relations:
- Enrolls { Student: N; Course: M; Teacher: 1; Term }

ERD: key, derived and composite attributes

Attribute marks and nesting:

attr = name [ "*" | "**" ] [ "#" ] [ "{" attr { ";" attr } "}" ] ;

• User ID *: key, bold and underlined (W125 when an entity has none).
• User ID **: foreign key, no mark drawn yet.
• Age #: derived, dashed oval.
• Address { Country; City }: composite; its children are drawn farther out on the same side, any depth.

Example (docs/examples/erd-attributes.ddr):

Type: ERD
Title: Users and Orders

# key `*`, foreign key `**`, derived `#`, composite `{ }`
Entities:
- User {
    User ID *
    Name
    Age #
    Address {
      Country
      City
      District
    }
  }
- Order { *Order ID; Order Date; User ID **; Total # }

Relations:
- Places { User: 1; Order: N }

ERD: optional cardinality

The cardinality after Entity: is optional:

member = entity_name [ ":" card ] ;   (* card: 1 | M | N | 0..1 | 1..N | ... ; free text *)

• Employee: 0..1 prints 0..1 beside Employee.
• Employee alone joins the entity and prints nothing (no default cardinality is assumed).

Example (docs/examples/erd-optional-card.ddr):

Type: ERD
Title: Employees and parking spots

Entities:
- Employee { Employee ID *; Name }
- Parking Spot { Spot ID *; Level }
- Department { Department ID *; Name }

Relations:
- Uses { Employee: 0..1; Parking Spot: 0..1 }
- Works In { Employee; Department }

Documents (.tdr) and use case specifications

Markdown documents with a header and directives that embed live diagrams and use case specification tables.

• Header: none (a .tdr file)
• File: .tdr
• Views: page preview

Grammar:

file      = [ { key ":" value NL } "---" NL ] markdown ;
directive = "::diagram[" path "]" [ "{" "view=" q [ "caption=" q ] "}" ]
          | "::usecases[" path "]" [ "{" "title=" q "}" ] ;

• The body is CommonMark + GFM tables; callouts use > [!NOTE].
• ::diagram[path]{view="overview" caption="…"} embeds a live figure; view defaults to the first view.
• ::usecases[path]{title="…"} prints one specification table per use case. The CLI prints the same tables: ddr spec -format html|md|json file.ddr.
• An unknown file or view shows an inline error box instead of failing the page.
• ddr check and the MCP check tool are for .ddr files only: given a .tdr document they report only E108 (a file named .tdr, or a file without a .ddr extension whose header has no Type: and ends with ---). Check each embedded .ddr file instead.

Example (docs/examples/document.tdr):

Title: Online Store requirements
Author: Product Team
---

# Introduction

This document describes the Online Store. Each figure is a live view of a
`.ddr` file, so it stays in sync with the diagram source.

::diagram[diagrams/usecase.ddr]{view="overview" caption="Use cases"}

## Use case specifications

::usecases[diagrams/usecase.ddr]{title=""}