claude-project-instructions.txt

# Draw.io Diagram Generation

When the user requests any visual diagram, use draw.io to create it.

## Supported Diagrams

Draw.io supports virtually any diagram type:
- **Standard**: Flowcharts, org charts, mind maps, timelines, Venn diagrams
- **Software**: UML (class, sequence, activity, use case), ERD, architecture diagrams
- **Cloud/Infrastructure**: AWS, Azure, GCP, Kubernetes, network topology
- **Engineering**: Electrical circuits, digital logic, P&ID, floor plans
- **Business**: BPMN, value streams, customer journeys, SWOT
- **UI/UX**: Wireframes, mockups, sitemaps
- **And more**: Infographics, data flows, decision trees, etc.

## Format Selection

Choose the optimal format for the task:

| Format | Best For |
|--------|----------|
| **Mermaid** | Flowcharts, sequences, ERD, Gantt, state diagrams, class diagrams |
| **CSV** | Hierarchical data (org charts), bulk import from spreadsheets |
| **XML** | Complex layouts, precise positioning, custom styling, icons, shapes |

## URL Generation

Execute this Python code to generate the draw.io URL and output it as an HTML artifact:

```python
import json, re, zlib, base64
import xml.etree.ElementTree as ET
from urllib.parse import quote

# Set these variables:
diagram_type = "mermaid"  # "mermaid", "xml", or "csv"
diagram_code = """graph TD
    A[Start] --> B[End]"""

if diagram_type == "xml":
    # Repair the common slips: text around the diagram, < or a stray & in an
    # attribute value, the default layer written as its own parent
    found = re.search(r"<mxfile[\s\S]*?</mxfile>|<mxGraphModel[\s\S]*?</mxGraphModel>", diagram_code)
    if found and diagram_code.strip() != found.group(0):
        diagram_code = found.group(0)
    diagram_code = re.sub(r'="([^"]*)"', lambda m: '="' + re.sub(r"&(?!(?:amp|lt|gt|quot|apos|#[0-9]+|#x[0-9a-fA-F]+);)", "&amp;", m.group(1).replace("<", "&lt;")) + '"', diagram_code)
    diagram_code = re.sub(r'<mxCell id="([^"]+)" parent="\1"\s*/>', r'<mxCell id="\1" parent="0"/>', diagram_code)
    # Stops with an error if the XML is still not well-formed: fix it and run again
    ET.fromstring(diagram_code)

# Generate compressed URL
encoded = quote(diagram_code, safe='')
c = zlib.compressobj(9, zlib.DEFLATED, -15)
raw_deflate = c.compress(encoded.encode('utf-8')) + c.flush()
data = base64.b64encode(raw_deflate).decode()

# XML opens as #R (the compressed XML as it is); draw.io converts Mermaid and CSV from #create
if diagram_type == "xml":
    url = f"https://app.diagrams.net/?pv=0&grid=0#R{quote(data, safe='')}"
else:
    payload = json.dumps({"type": diagram_type, "compressed": True, "data": data})
    url = f"https://app.diagrams.net/?pv=0&grid=0#create={quote(payload, safe='')}"

# Output as HTML page
print(f"""<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<style>
  body {{
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
    display: flex;
    justify-content: center;
    align-items: center;
    min-height: 100vh;
    margin: 0;
    background: #f8f9fa;
  }}
  .card {{
    text-align: center;
    background: white;
    border-radius: 12px;
    padding: 40px;
    box-shadow: 0 2px 8px rgba(0,0,0,0.1);
  }}
  .card h2 {{
    margin: 0 0 8px;
    color: #1a1a1a;
  }}
  .card p {{
    margin: 0 0 24px;
    color: #666;
  }}
  .btn {{
    display: inline-block;
    padding: 14px 32px;
    background: #4285f4;
    color: white;
    text-decoration: none;
    border-radius: 8px;
    font-size: 16px;
    font-weight: 500;
    transition: background 0.2s;
  }}
  .btn:hover {{
    background: #3367d6;
  }}
</style>
</head>
<body>
  <div class="card">
    <h2>Diagram Ready</h2>
    <p>Click below to open your diagram in draw.io</p>
    <a class="btn" href="{url}" target="_blank" rel="noopener noreferrer">
      Open in draw.io
    </a>
  </div>
</body>
</html>""")
```

## XML Reference

For draw.io XML, follow the condensed XML rules (skeleton, vertex and edge templates, labels, shapes, the layout grid, containers, swimlanes, edge styles). Copy the contents of the following file into your Claude Project alongside these instructions:
https://github.com/jgraph/drawio-mcp/blob/main/shared/xml-essentials.md

Only if you need layers, tags, metadata and placeholders, tables, cross-functional grids or dark-mode colors, also add the full XML reference. It describes the draw.io MCP servers, so its `search_shapes` tool and `postLayout` / `routing` options don't apply here — place the nodes on the layout grid instead:
https://github.com/jgraph/drawio-mcp/blob/main/shared/xml-reference.md

## Format Examples

### Mermaid
```
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
```

### XML (draw.io native)
```xml
<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <mxCell id="2" value="Box" style="rounded=1;fillColor=#d5e8d4;" vertex="1" parent="1">
      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
    </mxCell>
  </root>
</mxGraphModel>
```

### CSV (hierarchical data)
```
# label: %name%
# style: rounded=1;whiteSpace=wrap;html=1;
# connect: {"from":"manager","to":"name","invert":true}
# layout: auto
name,manager
CEO,
CTO,CEO
CFO,CEO
```

## Instructions

1. When a diagram is requested, determine the best format
2. Generate the diagram code
3. Execute the Python code to create the URL
4. **Create an HTML artifact** from the script output – this is the clickable link for the user

## CRITICAL: XML Well-Formedness

When generating draw.io XML, the output **must** be well-formed XML. In particular:
- **NEVER include ANY XML comments (`<!-- -->`) in the output.** XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
- Escape special characters in attribute values (`&amp;`, `&lt;`, `&gt;`, `&quot;`).

## CRITICAL: URL Output Rules

**NEVER type, retype, or reproduce the generated URL in your chat response.**

The URL contains compressed base64 data. Retyping it WILL corrupt it – even a single changed character breaks the link completely.

Instead, follow this process:
1. Execute the Python script
2. The script outputs a complete HTML page with the correct link embedded
3. Present the HTML output as an artifact (the link inside is guaranteed correct because it was generated by the script, not by you)
4. In your chat message, simply tell the user to click the button in the artifact

**DO NOT** copy the URL from the script output into your response text. The artifact IS the delivery mechanism for the link.