drawio-logical-diagrams

# Draw.io Logical Diagrams Creation

## Overview

Create professional logical diagrams in draw.io's native XML format for logical flow diagrams, system architecture visualizations, and abstract process representations using generic shapes and symbols.

## When to Use

- Creating logical flow diagrams showing data flow between system components
- Designing logical architecture diagrams (abstract system structure)
- Building BPMN process diagrams for business processes
- Drawing UML diagrams (class, sequence, activity, state)
- Creating data flow diagrams (DFD) for system analysis
- Making decision flowcharts with branching logic
- Visualizing system interactions and sequences
- Documenting logical system design without cloud specifics

**Do NOT use for:** AWS/Azure/GCP architecture diagrams (use `aws-drawio-architecture-diagrams`).

## Instructions

### Creating a Logical Diagram

1. **Analyze the request**: Understand the system/process to diagram
2. **Choose diagram type**: Flowchart, architecture, BPMN, UML, DFD, etc.
3. **Identify elements**: Determine actors, processes, data stores, connectors
4. **Draft XML structure**: Create the mxGraphModel with proper root cells
5. **Add shapes**: Create mxCell elements with appropriate styles
6. **Add connectors**: Link elements with edge elements
7. **Validate XML**: Verify XML is well-formed and all IDs are unique (see validation checklist below)
8. **Output**: Write the .drawio file for the user

### XML Validation Checklist

Before outputting the file, verify:
- [ ] All tags are properly closed (no unclosed `<mxCell>`, `</mxGeometry>`, etc.)
- [ ] All cell IDs are unique (0 and 1 are reserved root cells, use sequential integers starting from 2)
- [ ] All `source` and `target` attributes reference existing cell IDs
- [ ] All `parent` attributes reference existing cell IDs
- [ ] All coordinates (x, y, width, height) are positive numbers
- [ ] Special characters are escaped (`<` → `&lt;`, `>` → `&gt;`, `&` → `&amp;`)
- [ ] Multi-line labels use `&#xa;` or `<br>` with `html=1` in style

### Key XML Components

| Component | Description |
|-----------|-------------|
| `mxfile` | Root element with host and version |
| `diagram` | Contains the diagram definition |
| `mxGraphModel` | Canvas settings (grid, page size) |
| `root` | Container for all cells (must include id="0" and id="1") |
| `mxCell` | Individual shapes (vertices) or connectors (edges) |

## Draw.io XML Structure

```xml
<mxfile host="app.diagrams.net" agent="Claude" version="24.7.17">
  <diagram id="logical-flow-1" name="Logical Flow">
    <mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1"
      tooltips="1" connect="1" arrows="1" fold="1" page="1"
      pageScale="1" pageWidth="1169" pageHeight="827" math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Shapes and connectors here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

**Key rules:**
- IDs "0" and "1" are reserved for root cells
- Use sequential integer IDs starting from "2"
- Use landscape orientation for architecture diagrams
- All coordinates must be positive and aligned to grid (multiples of 10)

## Generic Shapes and Styles

### Basic Shape Types

| Shape | Style |
|-------|-------|
| Rectangle | `rounded=0;whiteSpace=wrap;html=1;` |
| Rounded Rectangle | `rounded=1;whiteSpace=wrap;html=1;` |
| Ellipse/Circle | `ellipse;whiteSpace=wrap;html=1;` |
| Diamond | `rhombus;whiteSpace=wrap;html=1;` |
| Cylinder | `shape=cylinder3;whiteSpace=wrap;html=1;boundedLbl=1;` |
| Hexagon | `shape=hexagon;perimeter=hexagonPerimeter2;whiteSpace=wrap;html=1;` |
| Parallelogram | `shape=ext;double=1;rounded=0;whiteSpace=wrap;html=1;` |

### Standard Color Palette

| Element Type | Fill Color | Border Color | Usage |
|--------------|------------|--------------|-------|
| Process | `#dae8fc` | `#6c8ebf` | Operations/actions |
| Decision | `#fff2cc` | `#d6b656` | Conditional branches |
| Start/End | `#d5e8d4` | `#82b366` | Terminal states |
| Data/Store | `#e1f5fe` | `#0277bd` | Databases/files |
| Entity | `#f3e5f5` | `#7b1fa2` | External systems |
| Error/Stop | `#f8cecc` | `#b85450` | Error states |
| Actor/User | `#ffe0b2` | `#f57c00` | Users/actors |
| Container | `#f5f5f5` | `#666666` | Grouping areas |

### Connector Styles

**Standard flow:**
```
edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=1;strokeColor=#666666;strokeWidth=2;
```

**Dashed (alternative/optional):**
```
edgeStyle=orthogonalEdgeStyle;dashed=1;dashPattern=5 5;strokeColor=#666666;
```

**Arrow head styles:**
- `endArrow=classic;endFill=1` - Filled triangle
- `endArrow=open;endFill=0` - Open arrow
- `endArrow=blockThin;endFill=1` - Block arrow

## Diagram Types

| Type | Key Elements |
|------|--------------|
| Logical Flow | Actors (orange), Services (blue), Data Stores (cyan), External Systems (purple) |
| Logical Architecture | Layered containers with nested components |
| BPMN | Circle (Start/End), Rounded Rectangle (Activity), Diamond (Gateway) |
| UML Sequence | Vertical lifelines with message arrows |
| DFD | Square (Entity), Circle (Process), Open Rectangle (Data Store) |

## Reference Files

For detailed shape examples and style references, see:
- [shape-styles.md](references/shape-styles.md) - Complete shape examples and style reference
- [diagram-templates.md](references/diagram-templates.md) - Ready-to-use templates

## Examples

### Example 1: Order Processing Flow

**Request:** "Create a logical flow diagram showing order processing: customer submits order, system validates, if valid then processes payment and ships, if invalid notifies customer."

```xml
<mxfile host="app.diagrams.net" agent="Claude" version="24.7.17">
  <diagram id="order-flow-1" name="Order Processing">
    <mxGraphModel dx="1200" dy="800" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1"