What Files Are Loaded When Requesting a Flowchart in Diagram Design

When Diagram Design receives a flowchart request, it loads four critical resources: the Mermaid parser (mermaid_extract.py), the flowchart type reference (type-flowchart.md), the HTML rendering template (example-flowchart.html), and the verification script (verify-mermaid-import.py).

The Diagram Design skill (cathrynlavery/diagram-design) processes flowchart generation through a modular pipeline that separates parsing, validation, and presentation concerns. Understanding which files are loaded during a flowchart request helps developers debug rendering issues and extend the system's Mermaid diagram support.

The Core Parsing Engine

The primary entry point for flowchart processing resides in skills/diagram-design/scripts/mermaid_extract.py. This module contains the _parse_flowchart function that extracts the diagram kind, direction (TD, LR, etc.), and individual statements composing the flowchart structure.

When the system receives a raw Mermaid string, it invokes the parsing logic to identify flowchart-specific syntax before proceeding to validation or rendering stages.

# Example: parsing a raw Mermaid flowchart string

from skills.diagram_design.scripts.mermaid_extract import parse_diagram

mermaid_src = "flowchart LR\nA --> B"
diagram = parse_diagram(mermaid_src)   # <-- loads mermaid_extract.py

print(diagram["kind"], diagram["direction"])

# Output: flowchart LR

Type Definition and Validation References

After parsing, the system consults skills/diagram-design/references/type-flowchart.md to validate the flowchart structure against its supported specifications. This Markdown reference defines:

• Supported node shapes and syntax
• Sub-graph handling capabilities
• Directional flow constraints (TD, LR, BT, RL)
• Styling and annotation rules

This reference file drives the skill's validation logic and determines whether the parsed flowchart conforms to expected patterns before rendering proceeds.

Frontend Rendering Assets

For UI presentation, Diagram Design loads skills/diagram-design/assets/example-flowchart.html and its associated CSS variants. This HTML template provides:

• The container structure for SVG injection
• CSS hooks for styling different flowchart elements
• JavaScript integration points for interactive features

The template is fetched when the skill needs to display a preview or final render of the generated flowchart.

<!-- Example: HTML asset used to render a flowchart -->
<link rel="stylesheet" href="assets/example-flowchart.css">
<div class="diagram-container" data-kind="flowchart">
  <!-- rendered SVG will be injected here -->
</div>

CI Verification and Testing

While not part of the runtime request path, scripts/verify-mermaid-import.py plays a crucial role in the flowchart lifecycle. This verification script runs during development and continuous integration to ensure that:

• Flowchart parsing retains directional integrity
• The Mermaid import produces expected digests
• Syntax variations are handled consistently

Developers should note that changes to the core parser require validation through this script to prevent regressions in flowchart processing.

Complete File Loading Sequence

When tracing a flowchart request through the Diagram Design system, files load in the following order:

1. mermaid_extract.py – Parses the raw Mermaid syntax and identifies flowchart-specific constructs via _parse_flowchart
2. type-flowchart.md – Validates the parsed structure against flowchart specifications and supported features
3. example-flowchart.html – Provides the rendering container and styling hooks for UI presentation
4. verify-mermaid-import.py – Executes during CI to verify parsing integrity (development/testing phase)

Each file serves a distinct purpose in the pipeline, ensuring that flowcharts are correctly interpreted, validated, and displayed according to the repository's architecture standards.

Summary

• Primary Parser: skills/diagram-design/scripts/mermaid_extract.py handles flowchart syntax extraction and direction detection
• Type Reference: skills/diagram-design/references/type-flowchart.md defines validation rules, supported shapes, and sub-graph handling
• Rendering Template: skills/diagram-design/assets/example-flowchart.html supplies the frontend container and CSS hooks for diagram display
• Verification Script: scripts/verify-mermaid-import.py ensures parsing accuracy and digest consistency during development and CI

Frequently Asked Questions

How does Diagram Design determine if a request is for a flowchart specifically?

The system uses the _parse_flowchart function in mermaid_extract.py to inspect the raw Mermaid string. This function identifies the diagram kind by detecting the flowchart keyword and extracts directional parameters (LR, TD, etc.) to confirm the request type before loading subsequent validation and rendering resources.

Can I modify the flowchart validation rules without changing the parser?

Yes. The validation logic relies on type-flowchart.md in the references directory. You can update supported shapes, sub-graph rules, and styling constraints in this Markdown file without modifying the Python parsing logic in mermaid_extract.py, allowing for flexible specification updates that immediately affect validation behavior.

Where does the visual styling for flowcharts originate?

Visual presentation depends on example-flowchart.html and its associated CSS files in skills/diagram-design/assets/. These frontend assets provide the structural container and styling hooks that determine how the parsed flowchart appears in the user interface, separate from the backend parsing logic.

Is the verification script required for production deployments?

No. verify-mermaid-import.py operates specifically in development and CI environments to validate parsing integrity. Production flowchart requests bypass this script, proceeding directly from parsing (mermaid_extract.py) through validation (type-flowchart.md) to rendering (example-flowchart.html).

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