## UML Graph Studio — .umlgraph File Format Instructions

You are generating a `.umlgraph` file for UML Graph Studio.
This is a JSON file with the structure described below.
Save the output with the `.umlgraph` file extension.

### Top-Level Structure

```json
{
  "diagramId": "diag_unique_id",
  "diagramName": "My Diagram Title",
  "canvas": { "zoom": 1, "panX": 0, "panY": 0 },
  "nodes": [ ... ],
  "connections": [ ... ],
  "updatedAt": 1727300000000
}
```

### Node Object

Each node in the `nodes` array has these fields:

```json
{
  "id": "node_abc123",       // Unique string ID (prefix "node_")
  "x": 100,                  // X position on canvas (pixels)
  "y": 200,                  // Y position on canvas (pixels)
  "w": 220,                  // Width in pixels (min 140)
  "h": 160,                  // Height in pixels (min 90, optional — auto-calculated if omitted)
  "title": "Node Title",     // Short title displayed on the card
  "desc": "Description text here...",  // Multi-line description
  "priority": "P01",         // 1-3 character priority badge (e.g. P01, VIP, HI)
  "color": "#1e293b",        // Fill/background color (hex)
  "borderColor": "#3b82f6",  // Border color (hex)
  "shape": "rounded",        // Shape: "rounded" | "rectangle" | "diamond" | "cylinder" | "uml-class"
  "imageUrl": null,          // Base64 data URL for the main image/video, or null
  "mediaType": null,         // "image" | "video" | null
  "attributes": [],          // Array of strings for UML attributes (for uml-class shape)
  "methods": [],             // Array of strings for UML methods (for uml-class shape)
  "attachments": []          // Array of attachment objects (see below)
}
```

### Shapes

- `"rounded"` — Default rounded rectangle
- `"rectangle"` — Sharp-cornered rectangle
- `"diamond"` — Decision/condition diamond
- `"cylinder"` — Database cylinder
- `"uml-class"` — UML class box (uses attributes + methods arrays)

### Connection Object

Each connection in the `connections` array:

```json
{
  "id": "conn_xyz789",       // Unique string ID (prefix "conn_")
  "src": "node_abc123",      // Source node ID
  "tgt": "node_def456",      // Target node ID
  "lineType": "one-way",     // "one-way" (→) | "two-way" (↔) | "dotted" (- - -) | "solid" (——)
  "style": "curved",         // "curved" | "straight" | "ortho" (orthogonal elbow)
  "label": "calls API",      // Text label shown on the line
  "color": "#64748b"         // Line stroke color (hex)
}
```

### Attaching Files (Images, Videos, PDFs, Documents, etc.)

Files are stored as **base64 data URLs** inside the JSON, making the file fully self-contained.

#### Main Image/Video on Node

Set `imageUrl` to a base64 data URL string:

```json
{
  "imageUrl": "data:image/png;base64,iVBORw0KGgo...",
  "mediaType": "image"
}
```

For video:
```json
{
  "imageUrl": "data:video/mp4;base64,AAAAIGZ0eXA...",
  "mediaType": "video"
}
```

#### File Attachments Array

Each node can have multiple file attachments of ANY type.
Each attachment object in the `attachments` array:

```json
{
  "id": "att_unique_id",                              // Unique ID (prefix "att_")
  "name": "report.pdf",                                // Original filename with extension
  "type": "application/pdf",                            // MIME type
  "size": 245760,                                       // File size in bytes
  "data": "data:application/pdf;base64,JVBERi0xLj...", // Full base64 data URL
  "addedAt": "2026-09-25T12:00:00.000Z"                 // ISO timestamp
}
```

Common MIME types for attachments:
- Images: `image/png`, `image/jpeg`, `image/gif`, `image/webp`
- Videos: `video/mp4`, `video/webm`
- Documents: `application/pdf`, `application/msword`,
  `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
- Spreadsheets: `text/csv`,
  `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- Text: `text/plain`, `application/json`
- Archives: `application/zip`, `application/x-rar-compressed`

### Example: Complete Diagram

```json
{
  "diagramId": "diag_example_001",
  "diagramName": "System Architecture",
  "canvas": { "zoom": 1, "panX": 0, "panY": 0 },
  "nodes": [
    {
      "id": "node_frontend",
      "x": 60, "y": 60, "w": 240, "h": 140,
      "title": "Frontend App",
      "desc": "React SPA served via CDN with client-side state caching.",
      "priority": "P01",
      "color": "#1e293b",
      "borderColor": "#3b82f6",
      "shape": "rounded",
      "imageUrl": null,
      "attributes": [],
      "methods": [],
      "attachments": []
    },
    {
      "id": "node_api",
      "x": 420, "y": 60, "w": 240, "h": 140,
      "title": "API Gateway",
      "desc": "REST + GraphQL endpoints with rate limiting & JWT auth.",
      "priority": "P01",
      "color": "#1e293b",
      "borderColor": "#10b981",
      "shape": "rounded",
      "imageUrl": null,
      "attributes": [],
      "methods": [],
      "attachments": []
    },
    {
      "id": "node_db",
      "x": 780, "y": 60, "w": 220, "h": 140,
      "title": "PostgreSQL",
      "desc": "Primary relational database with read replicas and pooling.",
      "priority": "P02",
      "color": "#1e293b",
      "borderColor": "#f59e0b",
      "shape": "cylinder",
      "imageUrl": null,
      "attributes": [],
      "methods": [],
      "attachments": []
    }
  ],
  "connections": [
    {
      "id": "conn_1",
      "src": "node_frontend",
      "tgt": "node_api",
      "lineType": "one-way",
      "style": "curved",
      "label": "HTTP requests",
      "color": "#64748b"
    },
    {
      "id": "conn_2",
      "src": "node_api",
      "tgt": "node_db",
      "lineType": "two-way",
      "style": "curved",
      "label": "SQL queries",
      "color": "#64748b"
    }
  ],
  "updatedAt": 1727300000000
}
```

### Node Dimensions & Height Calculation (Ensure Full Text Visibility)

To guarantee that **all description text is completely visible without being hidden, clipped, or showing scrollbars**, accurately budget and specify each node's height `h`:

1. **Height Calculation Formula**:
   - **Base Header + Padding**: `~60px`
   - **Title**: `~22px` (add `+18px` if title is long and wraps to 2 lines)
   - **Description Text**: `ceil(characterCount / (w / 7.5)) * 16px + 10px`
     - Example: 150 chars at `w = 240px` (~32 chars/line) = `5 lines * 16px + 10px = 90px`
   - **Image or Video (`imageUrl`)**: Add `+150px`
   - **UML Attributes & Methods**: Add `+18px` per item (for `uml-class`)
   - **File Attachments Badge**: Add `+24px` (if `attachments.length > 0`)
   - **Recommended Height Guidelines**:
     - Compact node with 1-line description: `h: 110 – 140`
     - Standard node with 2-4 lines of description: `h: 160 – 240`
     - Multimedia node with image/schema + description: `h: 340 – 460`
     - Recommended width `w`: `220 – 280px` (or `380 – 460px` for large chemical/architecture cards)

### Overlap-Free Layout & Coordinate Calculation (x, y)

**CRITICAL: Nodes must NEVER overlay or overlap each other.** Calculate coordinates with strict geometric spacing:

1. **Vertical Spacing in the Same Column**:
   - Every node below another node MUST start after the previous node's full height plus a clear vertical gap:
     `y[next] = y[current] + h[current] + gapY`
   - **`gapY` MUST be at least `50px` to `80px`** (never use small fixed increments like 100px or 150px if cards are 300px+ tall!).
   - Example column stacking with 320px tall cards:
     - Node 0: `y = 60`, `h = 320`
     - Node 1: `y = 60 + 320 + 60 = 440`, `h = 320`
     - Node 2: `y = 440 + 320 + 60 = 820`, `h = 320`

2. **Horizontal Column Spacing**:
   - Arrange connected flows into parallel vertical columns (e.g. Column 0: Inputs/Sources, Column 1–2: Middle Entities/Layers, Column 3: Outputs/Storage).
   - Space columns so lines and labels breathe without touching cards:
     `x[nextColumn] = x[currentColumn] + width[currentColumn] + gapX`
   - **`gapX` MUST be at least `100px` to `160px`**.
   - Example: Col 0 at `x: 60` (`w: 260`), Col 1 at `x: 60 + 260 + 120 = 440` (`w: 260`), Col 2 at `x: 440 + 260 + 120 = 820`.

3. **Multi-Column Balance**:
   - Keep at most 6–10 nodes per column. If a category has more nodes (e.g. 20 items), split them across adjacent parallel columns rather than making a single 8,000px vertical tower.

### Important Rules

1. All IDs must be unique strings
2. Node IDs should start with "node_", connection IDs with "conn_", attachment IDs with "att_"
3. `src` and `tgt` in connections must reference existing node IDs
4. Files/images/videos MUST be base64 data URLs (starting with "data:")
5. The output must be valid JSON
6. Save with `.umlgraph` file extension
7. Keep `attachments` as an empty array `[]` if no files are attached
8. `imageUrl` should be `null` (not undefined) when no image is set