EdrawMax Diagrams AI Skill (edrawmax-diagrams)

An AI Agent Skill and programmatic Python engine for AI assistants (Antigravity IDE, Gemini, etc.) to author, inspect, audit, and batch-generate native, fully editable Wondershare EdrawMax (.eddx) diagrams from declarative JSON specifications.

---

🤖 About This AI Skill

This repository is packaged as a ready-to-use AI Agent Skill (defined in SKILL.md). It empowers AI agents to generate professional, native EdrawMax diagrams automatically without needing manual GUI interaction.

How AI Agents Use This Skill:

• Natural Language → Native .eddx: When a user requests a Data Flow Diagram (DFD), Use Case diagram, or Activity diagram, the AI agent authors a JSON spec and compiles it directly into an .eddx file.
• Conversion & Batch Generation: Converts text diagrams (Mermaid, PlantUML, Visio .vsdx) into native EdrawMax diagrams for SRS documents, theses, or system design specifications.
• Template-Based XML cloning: The AI agent never has to write raw XML geometry; the engine clones real shapes directly from live reference .eddx templates.

---

🌟 Overview

Drawing dozens of software architecture or systems analysis diagrams manually in EdrawMax is slow, and modifying them later (e.g., updating a process name or rerouting flows) is tedious.

This skill treats diagrams as declarative code. Diagrams are written as structured JSON specifications that can be version-controlled with Git, validated, and programmatically compiled in seconds into native .eddx files.

Why this approach works:

• No hardcoded XML geometry: Instead of manually building complex SVG/XML geometry, this tool uses reference .eddx template files as live shape libraries. Shape XML elements are cloned directly from EdrawMax itself, preserving original formatting, control points, formulas (F), and shape numbers.
• True Connector Glue: Connectors are bound to shape connection points (CPoints) and indexed in the internal <Connects> table. When you open the generated .eddx file in EdrawMax, arrows move dynamically with shapes when dragged.
• Smart Orthogonal Router: An integrated A* + simple-path routing engine navigates connectors around shapes, handles line jumping (bridges), prevents overlap, and aligns flow labels with clean text clipping.
• Multiple Layout Modes: Dedicated auto-layout engines (Radial for DFDs, Swimlane for Activity diagrams, Usecase layouts, Column grids) or manual x,y coordinate overrides.

---

🚀 Supported Diagram Types

Diagram Type	Spec / Template Key	Layout Engine	Supported Elements
Data Flow Diagram (DFD)	dfd	radial	Processes (Gane-Sarson P1), Data Stores (D1), External Entities (E1), Sister Entities (P3:), System Boundaries, Duplicated Satellites
Use Case Diagram	usecase	usecase	Actors, Use Cases, System Boundaries, Associations, Extend / Include relations
Activity Diagram	activity	swimlane	Start/End States, Actions/States, Decision Diamonds, Vertical Swimlanes

---

📁 Repository Structure

.
├── SKILL.md                      # Antigravity AI Agent Skill definition
├── README.md                     # Project documentation (this file)
├── scripts/
│   ├── eddx_gen.py               # Core Generator: JSON Spec → Native .eddx
│   ├── router.py                 # Orthogonal A* Router & lane collision solver
│   ├── eddx_audit.py             # Quantitative layout quality auditor (intersections, collisions)
│   ├── eddx_preview.py           # Fast SVG rendering engine for quick visual inspection
│   ├── uml_audit.py              # Pre-generation validator against UML 2.5 rules
│   ├── eddx_inspect.py           # Reverse-engineering tool for extracting shapes from .eddx
│   └── progress.py              # Build metrics & tracking helper
├── assets/
│   └── templates/                # Live .eddx template files & default JSON specs
│       ├── dfd.eddx / dfd.json
│       ├── usecase.eddx / usecase.json
│       └── activity.eddx / activity.json
└── references/
    ├── eddx-format.md            # Reverse-engineered structure of the .eddx ZIP/XML format
    └── dfd.md                    # Gane & Sarson DFD rules, level balancing, & guidelines

---

⚙️ Installation & Requirements

• Python 3.8+
• Dependencies: Standard Python library only (xml.etree.ElementTree, zipfile, json, math, heapq, argparse). No third-party package installation required for core .eddx generation!

---

💻 Quick Start & Usage

1. Generating an .eddx File from a JSON Spec

Run eddx_gen.py providing a JSON spec file and your target .eddx output path:

python scripts/eddx_gen.py path/to/spec.json -o output.eddx

Optionally specify a custom template descriptor:

python scripts/eddx_gen.py path/to/spec.json -o output.eddx -t assets/templates/dfd.json

2. Rendering a Quick SVG Preview

Check your diagram layout visually without opening EdrawMax:

python scripts/eddx_preview.py output.eddx -o preview.svg

3. Running Layout Quality Audit

Evaluate layout quality metrics (collisions, overlapping lines, label intersections, elbow counts):

python scripts/eddx_audit.py output.eddx

4. Validating UML Specs

Ensure your specification complies with UML 2.5 standards before generating:

python scripts/uml_audit.py path/to/spec.json

---

📝 Example JSON Specification

Here is an example specification for a Data Flow Diagram (DFD Level 1):

{
  "diagram": "dfd",
  "title": "A-P3 — Questionnaire Processing & Estimation",
  "layout": {
    "mode": "radial",
    "margin": 90,
    "col_gap": 215,
    "row_gap": 70,
    "duplicate": {
      "min_degree": 3,
      "types": ["store", "external"]
    }
  },
  "nodes": [
    {"id": "E1",  "type": "external", "num": "A-E1",   "label": "Applicant"},
    {"id": "P1",  "type": "process",  "num": "A-P3.1", "label": "Display Questionnaire Step"},
    {"id": "P2",  "type": "process",  "num": "A-P3.2", "label": "Calculate Cost Estimate"},
    {"id": "D5",  "type": "store",    "num": "A-D5",   "label": "Question Bank"},
    {"id": "N1",  "type": "entity",   "label": "A-P4: Billing & Collection"},
    {"id": "BND", "type": "boundary", "label": "A-P3 Boundary", "members": ["P1", "P2"]}
  ],
  "flows": [
    {"from": "E1", "to": "P1", "label": "Project & Building Details"},
    {"from": "D5", "to": "P1", "label": "Questions List"},
    {"from": "P1", "to": "P2", "label": "Responses Data"},
    {"from": "P2", "to": "N1", "label": "Approved Estimate"}
  ]
}

Key Spec Properties:

• diagram: Template type (dfd, usecase, activity).
• nodes: List of diagram elements.
  • id: Internal unique key for connecting flows (not displayed).
  • num: Element identifier tag (e.g. process number A-P3.1).
  • label: Main display text (supports UTF-8, Arabic, English, multi-line).
  • x, y (optional): Manual absolute coordinates if auto-layout is not desired.
• flows / edges: Connectors between node IDs.
  • from / to: Source and target node IDs.
  • label (optional): Connector label text.
  • bidir: true for bidirectional arrows.
  • no_jump: true to skip line-bridge curves on intersection.

---

🛠 Advanced Features & Architecture

🔄 Radial Layout for DFDs

In DFDs, processing flows primarily between processes while external entities and data stores connect to one or two processes. The radial layout engine:

1. Places the process chain linearly along the central axis (horizontal or vertical based on diagram aspect ratio).
2. Distributes external entities and data stores around an enclosing ellipse directly opposite the processes they serve.
3. Automatically snaps satellite items adjacent to their main process, reducing line crossings dramatically (observed reduction from 166 to 27 intersections on complex enterprise DFDs).

🛣 Orthogonal Routing Engine (router.py)

• Evaluates candidate paths (L-shaped, Z-shaped, and A* grid paths) using a cost function balancing: $$\text{Cost} = \text{Intersections} \times C_{\text{cross}} + \text{Turns} \times C_{\text{turn}} + \text{Overlays} \times \infty + \text{Length}$$
• Detour Limiter: Prevents unrealistic 1000px detours around minor intersections.
• Label Clipping: Renders text blocks with explicit white background fill masks (BkColor="#ffffff") to cleanly clip flow lines behind labels.

📄 Print & Page Setup (PrintSetup)

Rather than scaling down text to unreadable small fonts to force A4 compliance, eddx_gen.py maintains optimal 1:1 readable font sizes and configures native .eddx PrintSetup with FittoSheet="TRUE". This ensures the diagram exports cleanly to a single A4 PDF page without compromising editing readability in EdrawMax.

---

🔍 Extending & Adding New Templates

To add a new diagram type (e.g., Sequence Diagram or ERD):

1. Create a representative diagram in EdrawMax and save it as assets/templates/your_type.eddx.
2. Run eddx_inspect.py to extract shape definitions and CPoints:

   python scripts/eddx_inspect.py assets/templates/your_type.eddx

3. Create a corresponding template JSON descriptor (assets/templates/your_type.json) mapping node types to shape IDs.

For full technical specifications of the .eddx file format (ZIP archive layout, formula syntax, transform properties, ConPoints, and <Connects> tables), see references/eddx-format.md.

---

📖 Related References

• EDDX Format Specification — Reverse-engineered XML & ZIP structure details.
• DFD Gane & Sarson Rules — Conventions, balancing rules, and level decomposition standards.
• Antigravity Skill Definition — Detailed AI instructions for edrawmax-diagrams.

---

📄 License

MIT / Open Source — feel free to use, extend, and integrate into your documentation pipelines.