# agents365-ai/drawio-skill architecture

> Architecture diagram of the GitHub repository agents365-ai/drawio-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agents365-ai/drawio-skill
- Repository: https://github.com/agents365-ai/drawio-skill

## Overview

1. **What this repo is**
   - This is a **tooling/skill repository**, not a traditional application.
   - Its core product is a **single Agent Skills package** (`skills/drawio-skill/SKILL.md`) that teaches AI agents to generate and refine **draw.io diagrams** from natural language or from source code structure.

2. **Primary boundary: the skill package**
   - The main runtime boundary is the `skills/drawio-skill/` folder.
   - `SKILL.md` is the entry contract for agents.
   - Everything else in the repo supports that skill: reference docs, helper scripts, style data, shape indexes, tests, and GitHub Pages docs.

3. **End-to-end diagram generation flow**
   - User prompt or codebase description enters the skill.
   - The skill plans the diagram, emits **draw.io XML**, then exports via the **native draw.io desktop CLI** to raster/vector formats such as PNG, SVG, PDF, and JPG.
   - It then performs a **visual self-check** against the rendered PNG and can auto-fix issues before presenting the result back to the user.
   - The repo’s architecture is therefore a pipeline: **intent → layout/design → draw.io XML → render/export → validation/self-check → iterative refinement**.

4. **Codebase visualization subsystem**
   - A major feature is turning source trees into structure diagrams.
   - The extractors in `skills/drawio-skill/scripts/` cover:
     - `pyimports.py`
     - `jsimports.py`
     - `goimports.py`
     - `rustimports.py`
     - `pyclasses.py`
   - These produce graph data, which is then passed to `autolayout.py` to generate an editable `.drawio` diagram.
   - This forms a separate input path from the natural-language diagram flow: **source code → import/class graph → auto-layout → draw.io**.

5. **Layout and graph-processing boundary**
   - `autolayout.py` is the bridge between abstract graph data and visual diagram geometry.
   - The repo explicitly depends on **Graphviz** for placement and routing when doing larger code-structure diagrams.
   - The layout subsystem also supports:
     - transitive reduction,
     - grouped/nested containers,
     - cleaner orthogonal routing around nodes.
   - This is the key “algorithmic” layer of the repo.

6. **Shape and icon resolution subsystem**
   - `shapesearch.py` resolves exact official draw.io shapes from a large local index (`skills/drawio-skill/data/shape-index.json.gz`).
   - `aiicons.py` maps AI/LLM brand names to logo styles using `lobe-icons.json`.
   - These two scripts are important because they prevent diagrams from degrading into generic boxes or guessed shape names.
   - Architecturally, this is a **local lookup layer** that enriches diagram nodes with vendor-specific visual identity.

7. **Style system**
   - The repo includes a style-presets subsystem under `skills/drawio-skill/styles/`.
   - Built-in presets live in `styles/built-in/` and are backed by `schema.json`.
   - The skill can also learn styles from an existing `.drawio` file or image, which means style extraction is a separate concern from layout and content generation.
   - This layer controls colors, fonts, edge styles, and shape appearance.

8. **Validation and self-healing**
   - `validate.py` provides deterministic linting for generated `.drawio` files.
   - The README describes a visual feedback loop where rendered PNGs are inspected for issues like overlaps, clipped labels, or stacked edges.
   - This gives the repo a two-step quality gate:
     1. **structural validation** on the XML/graph artifact,
     2. **visual validation** on the rendered image.
   - That separation is a key architectural boundary.

9. **Supporting utilities**
   - `encode_drawio_url.py` supports creating diagrams.net links or encoded diagram payloads.
   - Language-specific helpers like `goimports.py`, `jsimports.py`, `pyimports.py`, and `rustimports.py` are focused extractors rather than shared libraries.
   - `repair_png.py` indicates the repo also deals with render artifacts, not just source diagrams.

10. **Data and reference assets**
   - `skills/drawio-skill/data/` contains the large shape index and AI-logo metadata.
   - `skills/drawio-skill/references/` contains domain knowledge for autolayout, diagram types, shapes, presets, extraction, and troubleshooting.
   - `assets/` contains example diagrams and visual documentation used by the README and docs, which helps illustrate expected output but is not part of the runtime pipeline.

11. **Documentation and distribution**
   - `docs/` is the published documentation site, including installation, usage, comparisons, and style preset guides.
   - The repo is designed for distribution through agent ecosystems and plugin marketplaces, plus manual install.
   - That means the repo serves both as **runtime skill payload** and as **documentation artifact**.

12. **Tests and CI**
   - `tests/test_scripts.py` indicates the automated tests focus on the helper scripts rather than a full application stack.
   - GitHub Actions workflows handle repo-level verification and a sync process for a broader 365-skills ecosystem.
   - CI is therefore centered on script correctness and packaging integrity, not deployment of a service.

13. **External dependencies that matter architecturally**
   - **draw.io desktop CLI** is the essential render/export dependency.
   - **Graphviz** is required for the auto-layout path.
   - **Node** appears only for the optional `npx` installer, not for the skill logic itself.
   - The repo also references CDN-backed icon rendering for some AI logos when not embedded, which affects offline/online behavior.

14. **How to diagram the architecture**
   - A good architecture diagram should show three main lanes:
     - **Agent/skill interface**: prompt in, diagram intent out.
     - **Content generation and enrichment**: diagram planning, shape lookup, style selection, codebase extraction, graph layout.
     - **Validation/rendering**: draw.io XML generation, CLI export, PNG self-check, iterative fix loop.
   - The boundaries to emphasize are:
     - natural language vs codebase-derived input,
     - abstract graph data vs rendered diagram,
     - deterministic validation vs visual feedback refinement.

Main entry points: [`skills/drawio-skill/scripts/autolayout.py`](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/autolayout.py) (Autolayout), [`skills/drawio-skill/scripts/validate.py`](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/validate.py) (Validator), [`skills/drawio-skill/scripts/pyimports.py`](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/pyimports.py) (Python imports), [`skills/drawio-skill/scripts/jsimports.py`](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/jsimports.py) (JS imports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_skill["Skill package"]
  node_skill_entry["SKILL.md<br/>agent skill entry<br/>[SKILL.md]"]
  node_intent_plan["Diagram plan<br/>prompt-to-design"]
  node_xml_emit["draw.io XML<br/>diagram markup"]
end

subgraph group_group_layout["Graph & layout"]
  node_source_extract["Code extractors<br/>code graph input"]
  node_pyimports["Python imports<br/>extractor<br/>[pyimports.py]"]
  node_jsimports["JS imports<br/>extractor<br/>[jsimports.py]"]
  node_goimports["Go imports<br/>extractor<br/>[goimports.py]"]
  node_rustimports["Rust imports<br/>extractor<br/>[rustimports.py]"]
  node_pyclasses["Python classes<br/>extractor<br/>[pyclasses.py]"]
  node_autolayout["Autolayout<br/>graph layout<br/>[autolayout.py]"]
  node_graphviz(("Graphviz<br/>external layout engine"))
end

subgraph group_group_style["Shape & style"]
  node_shape_search["Shape search<br/>shape index lookup<br/>[shapesearch.py]"]
  node_ai_icons["AI icons<br/>logo mapping<br/>[aiicons.py]"]
  node_style_presets["Style presets<br/>style system<br/>[schema.json]"]
  node_shape_index[("Shape index<br/>shape catalog")]
end

subgraph group_group_quality["Validation & export"]
  node_validate["Validator<br/>xml lint<br/>[validate.py]"]
  node_repair_png["PNG repair<br/>render fixup<br/>[repair_png.py]"]
  node_drawio_cli["draw.io CLI<br/>export runtime"]
  node_visual_check(("Visual check<br/>self-check loop"))
  node_encode_url["URL encode<br/>share payload"]
end

subgraph group_group_docs["Docs & examples"]
  node_refs["References<br/>knowledge base<br/>[autolayout.md]"]
  node_docs_site["Docs site<br/>published docs<br/>[index.html]"]
  node_assets["Samples<br/>examples"]
end

subgraph group_group_ci["Automation"]
  node_tests["Script tests<br/>test suite<br/>[test_scripts.py]"]
  node_workflows["Workflows<br/>ci automation<br/>[tests.yml]"]
end

node_skill_entry -->|"accepts intent"| node_intent_plan
node_intent_plan -->|"resolves shapes"| node_shape_search
node_intent_plan -->|"resolves icons"| node_ai_icons
node_intent_plan -->|"applies style"| node_style_presets
node_intent_plan -->|"emits XML"| node_xml_emit
node_source_extract -->|"python"| node_pyimports
node_source_extract -->|"javascript"| node_jsimports
node_source_extract -->|"go"| node_goimports
node_source_extract -->|"rust"| node_rustimports
node_source_extract -->|"classes"| node_pyclasses
node_pyimports -->|"graph data"| node_autolayout
node_jsimports -->|"graph data"| node_autolayout
node_goimports -->|"graph data"| node_autolayout
node_rustimports -->|"graph data"| node_autolayout
node_pyclasses -->|"graph data"| node_autolayout
node_autolayout -->|"routes via"| node_graphviz
node_autolayout -->|"lays out"| node_xml_emit
node_shape_search -->|"looks up"| node_shape_index
node_ai_icons -->|"consults"| node_shape_index
node_style_presets -->|"informed by"| node_refs
node_xml_emit -->|"linted by"| node_validate
node_validate -->|"exports via"| node_drawio_cli
node_drawio_cli -->|"renders PNG"| node_visual_check
node_visual_check -->|"fixes artifacts"| node_repair_png
node_repair_png -.->|"iterates"| node_xml_emit
node_encode_url -->|"encodes"| node_xml_emit
node_docs_site -->|"publishes guides"| node_refs
node_assets -->|"illustrates"| node_docs_site
node_tests -->|"checks"| node_validate
node_workflows -->|"runs"| node_tests

click node_skill_entry "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/SKILL.md"
click node_pyimports "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/pyimports.py"
click node_jsimports "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/jsimports.py"
click node_goimports "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/goimports.py"
click node_rustimports "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/rustimports.py"
click node_pyclasses "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/pyclasses.py"
click node_autolayout "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/autolayout.py"
click node_shape_search "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/shapesearch.py"
click node_ai_icons "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/aiicons.py"
click node_style_presets "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/styles/schema.json"
click node_shape_index "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/data/shape-index.json.gz"
click node_validate "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/validate.py"
click node_repair_png "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/repair_png.py"
click node_encode_url "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/encode_drawio_url.py"
click node_refs "https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/references/autolayout.md"
click node_docs_site "https://github.com/agents365-ai/drawio-skill/blob/main/docs/index.html"
click node_assets "https://github.com/agents365-ai/drawio-skill/blob/main/assets/demo-layered.drawio"
click node_tests "https://github.com/agents365-ai/drawio-skill/blob/main/tests/test_scripts.py"
click node_workflows "https://github.com/agents365-ai/drawio-skill/blob/main/.github/workflows/tests.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill_entry,node_intent_plan,node_xml_emit toneBlue
class node_source_extract,node_pyimports,node_jsimports,node_goimports,node_rustimports,node_pyclasses,node_autolayout,node_graphviz toneAmber
class node_shape_search,node_ai_icons,node_style_presets,node_shape_index toneMint
class node_validate,node_repair_png,node_drawio_cli,node_visual_check,node_encode_url toneRose
class node_refs,node_docs_site,node_assets toneIndigo
class node_tests,node_workflows toneTeal
```

## Components

### Skill package

Core agent skill boundary and diagram generation pipeline.

- [SKILL.md](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/SKILL.md): agent skill entry · Primary contract for agents and the main entry point for diagram generation. · `skills/drawio-skill/SKILL.md`
- **Diagram plan**: prompt-to-design · Turns user intent or source context into a diagram plan and layout strategy.
- **draw.io XML**: diagram markup · Intermediate editable diagram representation produced by the skill.

### Graph & layout

Codebase extraction, graph processing, and auto-layout.

- **Code extractors**: code graph input · Language-specific import and class extraction path for turning codebases into graph data.
- [Python imports](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/pyimports.py): extractor · Parses Python import structure for graph generation. · `skills/drawio-skill/scripts/pyimports.py`
- [JS imports](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/jsimports.py): extractor · Parses JavaScript and TypeScript import structure for graph generation. · `skills/drawio-skill/scripts/jsimports.py`
- [Go imports](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/goimports.py): extractor · Parses Go import structure for graph generation. · `skills/drawio-skill/scripts/goimports.py`
- [Rust imports](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/rustimports.py): extractor · Parses Rust module and import structure for graph generation. · `skills/drawio-skill/scripts/rustimports.py`
- [Python classes](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/pyclasses.py): extractor · Extracts Python class structure for codebase diagrams. · `skills/drawio-skill/scripts/pyclasses.py`
- [Autolayout](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/autolayout.py): graph layout · Bridges abstract graph data to diagram geometry and routing, including grouped layouts and transitive reduction. · `skills/drawio-skill/scripts/autolayout.py`
- **Graphviz**: external layout engine · Placement and routing engine used for larger structure diagrams.

### Shape & style

Shape lookup, icon mapping, and style preset resolution.

- [Shape search](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/shapesearch.py): shape index lookup · Resolves exact official draw.io shapes from the local shape index. · `skills/drawio-skill/scripts/shapesearch.py`
- [AI icons](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/aiicons.py): logo mapping · Maps AI and LLM brand names to icon styles and logo metadata. · `skills/drawio-skill/scripts/aiicons.py`
- [Style presets](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/styles/schema.json): style system · Built-in and learned style presets for colors, fonts, edges, and appearance. · `skills/drawio-skill/styles/schema.json`
- [Shape index](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/data/shape-index.json.gz): shape catalog · Large local catalog of draw.io shapes used to keep diagrams precise. · `skills/drawio-skill/data/shape-index.json.gz`

### Validation & export

Render/export, structural checks, and visual repair loop.

- [Validator](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/validate.py): xml lint · Deterministic checks for generated draw.io files. · `skills/drawio-skill/scripts/validate.py`
- [PNG repair](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/repair_png.py): render fixup · Repairs or adjusts rendered image artifacts used in the feedback loop. · `skills/drawio-skill/scripts/repair_png.py`
- **draw.io CLI**: export runtime · Native desktop CLI dependency for rendering and exporting diagrams.
- **Visual check**: self-check loop · Inspects rendered PNGs for overlaps, clipping, and stacking issues before refinement.
- [URL encode](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/scripts/encode_drawio_url.py): share payload · Builds diagrams.net links or encoded diagram payloads. · `skills/drawio-skill/scripts/encode_drawio_url.py`

### Docs & examples

Published documentation, references, and sample diagrams.

- [References](https://github.com/agents365-ai/drawio-skill/blob/main/skills/drawio-skill/references/autolayout.md): knowledge base · Domain references for autolayout, diagram types, shapes, presets, extraction, and troubleshooting. · `skills/drawio-skill/references/autolayout.md`
- [Docs site](https://github.com/agents365-ai/drawio-skill/blob/main/docs/index.html): published docs · Installation, usage, style preset, and comparison documentation. · `docs/index.html`
- [Samples](https://github.com/agents365-ai/drawio-skill/blob/main/assets/demo-layered.drawio): examples · Example diagrams and visual documentation assets. · `assets/demo-layered.drawio`

### Automation

Tests and repository workflows.

- [Script tests](https://github.com/agents365-ai/drawio-skill/blob/main/tests/test_scripts.py): test suite · Automated checks focused on helper scripts and packaging behavior. · `tests/test_scripts.py`
- [Workflows](https://github.com/agents365-ai/drawio-skill/blob/main/.github/workflows/tests.yml): ci automation · GitHub Actions for tests and ecosystem sync. · `.github/workflows/tests.yml`

## Connections

- SKILL.md → Diagram plan: accepts intent · The skill entry receives natural language or codebase-driven requests and starts planning.
- Diagram plan → Shape search: resolves shapes · Planning can request exact shapes for nodes.
- Diagram plan → AI icons: resolves icons · Planning can enrich AI-related nodes with branded icons.
- Diagram plan → Style presets: applies style · Style selection shapes colors, fonts, and edge appearance.
- Diagram plan → draw.io XML: emits XML · The plan is materialized into editable draw.io XML.
- Code extractors → Python imports: python · Python import graphs are extracted from source trees.
- Code extractors → JS imports: javascript · JavaScript import graphs are extracted from source trees.
- Code extractors → Go imports: go · Go import graphs are extracted from source trees.
- Code extractors → Rust imports: rust · Rust import graphs are extracted from source trees.
- Code extractors → Python classes: classes · Python class structure can be extracted for code diagrams.
- Python imports → Autolayout: graph data · Extractor output becomes layout-ready graph data.
- JS imports → Autolayout: graph data · Extractor output becomes layout-ready graph data.
- Go imports → Autolayout: graph data · Extractor output becomes layout-ready graph data.
- Rust imports → Autolayout: graph data · Extractor output becomes layout-ready graph data.
- Python classes → Autolayout: graph data · Extractor output becomes layout-ready graph data.
- Autolayout → Graphviz: routes via · Graphviz is used for placement and routing on larger diagrams.
- Autolayout → draw.io XML: lays out · Layout geometry is converted into final diagram XML.
- Shape search → Shape index: looks up · Exact official shapes are resolved from the local index.
- AI icons → Shape index: consults · Icon mapping is backed by local metadata and shape references.
- Style presets → References: informed by · Preset behavior is documented and described in references.
- draw.io XML → Validator: linted by · Generated XML is structurally validated before export.
- Validator → draw.io CLI: exports via · Validated diagrams are rendered and exported with the native CLI.
- draw.io CLI → Visual check: renders PNG · Rendered PNG output feeds the visual self-check loop.
- Visual check → PNG repair: fixes artifacts · Visual issues can trigger image repair or refinement.
- PNG repair → draw.io XML: iterates · Detected problems can send the workflow back for diagram refinement.
- URL encode → draw.io XML: encodes · Supports shareable encoded diagram payloads and links.
- Docs site → References: publishes guides · Documentation site presents installation, usage, and style guidance.
- Samples → Docs site: illustrates · Sample diagrams support documentation and visual examples.
- Script tests → Validator: checks · Tests focus on helper script behavior and expected outputs.
- Workflows → Script tests: runs · CI workflows execute repository checks and sync automation.