agents365-ai/drawio-skill

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.