How draw.io Import Converts and Redraws Diagrams at Different Detail Levels in Diagram Design

*The draw.io import process in Diagram Design uses a three-phase pipeline—extraction, detail-level mapping, and rendering—to transform raw .drawio files into diagrams that display at high, mid, or low abstraction levels without losing fidelity.

The Diagram Design repository provides a sophisticated workflow for importing draw.io diagrams and rendering them at varying levels of detail. This capability allows technical documentation to present architectural overviews to executives while preserving granular implementation details for engineering teams, all from a single source file.

---

The Three-Phase Import Pipeline

The import-drawio command orchestrates a complete transformation workflow that separates concerns across extraction, hierarchical mapping, and final rendering.

Phase 1: Extraction and Normalization

The helper script skills/diagram-design/scripts/drawio_extract.py handles the initial parsing of draw.io files. This script:

• Parses XML representations of .drawio files, including embedded PNG/SVG variants
• Extracts shapes, connectors, styling attributes, and custom data
• Normalizes the XML structure and resolves embedded resources
• Outputs a clean JSON model capturing hierarchy, geometry, and metadata for every node

python3 drawio_extract.py sample-architecture.drawio --page 1 --json

The extraction layer implements several security and integrity safeguards:

• Entity-DTD verification ensures extracted XML adheres to the draw.io DTD
• Compressed-entity handling automatically expands compressed draw.io files before parsing
• Decoy-SVG detection prevents malicious SVG payloads from injection

Phase 2: Detail-Level Mapping

After extraction, the core Diagram Design engine processes the JSON model. It applies container node identification and marker-first resolution (documented in ADR [0001] and ADR [0006]) to assign elements to abstraction tiers.

Detail Level	Rendering Behavior
High-level view	Retains only top-level containers and immediate children; internal groups collapse into placeholder shapes
Mid-level view	Displays container boundaries with logical groupings preserved; sub-components remain hidden
Low-level view	Renders all leaf nodes and precise connector routes; reproduces exact original layout

The marker-first resolution strategy determines which elements survive at each tier, ensuring consistent semantics across abstraction levels.

Phase 3: Rendering and Export

The processed model feeds into the rendering pipeline, which generates output in multiple formats:

• Markdown with embedded Mermaid
• Standalone HTML
• Static PNG/SVG

The pipeline applies styling rules from commands/import-drawio.md and respects the selected detail level throughout.

---

Command-Line Usage Examples

Generate a high-level architectural overview suitable for stakeholder presentations:

python3 drawio_extract.py sample-architecture.drawio --page 1 --json |
diagram-design --detail high --format mermaid > architecture-high.mmd

Produce a low-level implementation diagram with complete fidelity:

python3 drawio_extract.py sample-architecture.drawio --page 1 --json |
diagram-design --detail low --format mermaid > architecture-low.mmd

---

Programmatic API Access

The Python API provides fine-grained control over the import and rendering pipeline:

from diagram_design.drawio import DrawioExtractor, DiagramRenderer

# Load and normalize the draw.io file

extractor = DrawioExtractor("sample-architecture.drawio")
model = extractor.to_json(page=1)

# Render a mid-level diagram as Mermaid

renderer = DiagramRenderer(model)
mid_mermaid = renderer.render(detail="mid", fmt="mermaid")
print(mid_mermaid)

The DrawioExtractor class handles file parsing and normalization, while DiagramRenderer manages abstraction-level selection and format conversion.

---

Key Implementation Files

Understanding the source structure helps when extending or debugging the import workflow:

• skills/diagram-design/scripts/drawio_extract.py — Core extractor parsing draw.io XML and producing normalized JSON models
• commands/import-drawio.md — CLI reference documenting flags, detail levels, and output formats
• scripts/verify-drawio-import.py — Test harness validating the pipeline against fixture diagrams
• docs/adr/0001-static-by-default-single-pinned-controller.md — ADR explaining default static rendering strategy
• docs/adr/0006-client-profiles-and-marker-first-resolution.md — ADR detailing marker-first resolution for multi-detail abstraction

---

Summary

• The draw.io import workflow separates extraction, hierarchical mapping, and rendering into distinct phases
• drawio_extract.py normalizes raw draw.io XML into a structured JSON model
• Three detail levels (high, mid, low) control abstraction through container node detection and marker-first resolution
• Security safeguards include DTD verification, compressed entity handling, and decoy-SVG detection
• Output formats include Mermaid-embedded Markdown, HTML, and static images

---

Frequently Asked Questions

How does the draw.io import handle compressed files?

The extraction pipeline automatically detects and expands compressed draw.io files before XML parsing. This happens transparently in drawio_extract.py during the normalization phase, requiring no user intervention.

What is marker-first resolution in detail-level mapping?

Marker-first resolution is the strategy documented in ADR [0006] that prioritizes semantic markers (container boundaries, group labels) over individual elements when determining what renders at each abstraction tier. This ensures logical groupings remain visible even when internal details collapse.

Can I import specific pages from multi-page draw.io files?

Yes. Both the CLI (--page 1) and Python API (to_json(page=1)) accept page indices to target specific diagrams within a single .drawio file.

Is the low-level view pixel-perfect with the original draw.io rendering?

The low-level view reproduces exact connector routes and leaf node positions from the original file. Minor rendering differences may appear due to styling engine variations between draw.io and Diagram Design's output formats.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}