# What Files Are Loaded When Requesting a Flowchart in Diagram Design

> Discover the four essential files loaded for flowcharts in Diagram Design. Learn about the Mermaid parser, type reference, and HTML template for efficient diagram creation.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: internals
- Published: 2026-08-22

---

**When Diagram Design receives a flowchart request, it loads four critical resources: the Mermaid parser ([`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)), the flowchart type reference ([`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)), the HTML rendering template ([`example-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-flowchart.html)), and the verification script ([`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```python

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```html
<!-- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)** – Parses the raw Mermaid syntax and identifies flowchart-specific constructs via `_parse_flowchart`
2. **[`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)** – Validates the parsed structure against flowchart specifications and supported features
3. **[`example-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-flowchart.html)** – Provides the rendering container and styling hooks for UI presentation
4. **[`verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py) handles flowchart syntax extraction and direction detection
- **Type Reference**: [`skills/diagram-design/references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-flowchart.html) supplies the frontend container and CSS hooks for diagram display
- **Verification Script**: [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py)) through validation ([`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md)) to rendering ([`example-flowchart.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-flowchart.html)).