# Progressive Loading Architecture in diagram-design: On-Demand File Loading Explained

> Learn about progressive loading architecture in diagram-design. Discover how SKILL.md loads at startup and other files are fetched on-demand for efficient performance.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: architecture
- Published: 2026-09-13

---

**The progressive loading architecture in diagram-design ensures that the agent only reads files necessary for the specific request, loading [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) at startup and lazily fetching additional reference files like type-specific layouts or semantic patterns only when triggered by user input.**

The `cathrynlavery/diagram-design` repository implements this sophisticated loading strategy to minimize memory overhead and eliminate unnecessary I/O operations. Unlike monolithic systems that load entire libraries upfront, this architecture maintains a minimal working context that expands dynamically based on the specific diagram request, ensuring optimal performance regardless of the 39-type library size.

## How Progressive Loading Works in diagram-design

At startup, the agent initializes with only the skill name and description, keeping the initial memory footprint minimal. When a user submits a request, the core [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file loads immediately as the universal entry point. As implemented in the source code, additional reference files are pulled **only when they become relevant**—for example, loading [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) when behavior analysis is requested, or [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) when motion is specified.

This "load-on-demand" strategy ensures that routine static diagram requests incur the same cost regardless of how many diagram types exist in the repository. The architecture guarantees that adding new visual types does not increase runtime overhead for existing requests.

## What Loads When: Request-to-File Mapping

The specific files loaded depend entirely on the user's intent. According to the documentation in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), the progressive loader follows this mapping:

### Standard Diagram Types

For basic diagram generation, the system loads the core skill file plus exactly one type-specific reference:

- **Flowchart requests**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md)
- **Architecture diagrams**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-architecture.md)

### Semantic and Behavioral Analysis

When requests involve comparing behaviors or routing logic, the system loads additional semantic files:

- **Policy comparison requests**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) + [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md)

### Motion and Animation

Animation requires the optional motion contract in addition to base files:

- **Animated policy traces**: Loads prior selection + [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md)

### Import and Conversion Workflows

Existing file formats trigger specific import references:

- **Draw.io file conversion**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-drawio.md) + [`references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/output-spec.md) + the chosen type's reference
- **Mermaid block conversion**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/import-mermaid.md) + [`references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/output-spec.md) + the chosen type's reference

### Visual Primitives

Stylistic modifications load specialized primitive files:

- **Editorial callouts**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/primitive-annotation.md)
- **Sketchy/hand-drawn styles**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/primitive-sketchy.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/primitive-sketchy.md)
- **Terminal/CLI versions**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/primitive-terminal.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/primitive-terminal.md)

### Configuration and Onboarding

Specialized workflows load configuration references:

- **Skill onboarding**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/onboarding.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/onboarding.md) + [`references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/style-guide.md)
- **Client profiles**: Loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) + [`references/profiles.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/profiles.md) + `~/.diagram-design/profiles/acme.md` (or specific client file)

## Key Files in the Progressive Loading Architecture

The architecture relies on a hierarchical structure where files are organized by function and loaded selectively:

- **[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)**: Located at [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), this file serves as the mandatory entry point for every request and contains the complete "What loads when" documentation.
- **`references/type-*.md`**: Files like [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md) define layout grammars for specific visual types and load only when that type is explicitly requested.
- **[`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md)**: This library of behavior-centric patterns loads only when semantic routing or behavioral analysis is required.
- **[`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md)**: The motion contract loads exclusively for animated diagram requests, keeping static generation lightweight.
- **[`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md)**: The Architecture section contains the high-level progressive disclosure model illustrating how files load on demand.

## Progressive Loading in Action: Code Examples

The following examples demonstrate how the progressive loading architecture handles different request types using the built-in slash commands:

```bash

# Example 1: Simple flowchart request

# Loads only SKILL.md + type-flowchart.md

$ /diagram-design:make "flowchart of order processing"

# Output: assets/template.html → example-flowchart.html

```

```bash

# Example 2: Policy trace with animation

# Loads SKILL.md + semantic-patterns.md + type-flowchart.md + animation.md

$ /diagram-design:make "policy trace for request-id 42 with step-by-step animation"

# Output: assets/template-motion.html → example-policy-trace-animated.html

```

In both cases, the resulting HTML file contains only the content from the files that were loaded during that specific request, illustrating the tight working context maintained by the progressive loader.

## Performance Benefits of On-Demand Loading

The progressive loading architecture delivers specific technical advantages:

- **Constant runtime cost**: Every request loads exactly one type reference plus the core [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), meaning adding new diagram types to the 39-type library does not impact existing request performance.
- **Minimal I/O overhead**: The agent never reads reference files for diagram types not involved in the current request, eliminating unnecessary disk operations.
- **Scalable library growth**: The repository can expand to support additional visual types, semantic patterns, or animation features without increasing the memory footprint of simple diagram requests.

## Summary

- The **progressive loading architecture** in `cathrynlavery/diagram-design` initializes with minimal context and loads [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) as the universal entry point for every request.
- Additional files such as `references/type-*.md`, [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md), or [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) are loaded **only when relevant** to the specific user request.
- Standard diagram generation requires exactly two files: [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) plus one type-specific reference, ensuring consistent performance regardless of total library size.
- The architecture supports 39 diagram types plus optional features (animations, semantic analysis, imports) without penalizing simple static diagram requests.
- Documentation resides in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (file loading table) and [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) (high-level architecture overview).

## Frequently Asked Questions

### What is the first file loaded in the diagram-design progressive loading architecture?

The first file loaded is always [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) located at [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). This core skill descriptor serves as the mandatory entry point for every request, providing the agent with the necessary context to determine which additional reference files need to be loaded based on the user's specific diagram requirements.

### How does diagram-design handle animation requests differently from static diagrams?

For static diagrams, the system loads only [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) and the specific type reference (e.g., [`references/type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/type-flowchart.md)). When animation is requested, the progressive loader additionally pulls [`references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/animation.md) after loading the base files. This ensures that motion contracts and animation-specific logic are only incorporated when actually needed, preserving system resources for static generation workflows.

### Does adding new diagram types slow down existing requests in diagram-design?

No. Because the progressive loading architecture loads only one type reference per request—regardless of the total library size—adding new diagram types to the repository does not increase the runtime cost or memory footprint for existing requests. The system maintains constant performance characteristics even as the library expands beyond the current 39 types.

### Where is the progressive loading behavior documented in the repository?

The progressive loading behavior is documented in two primary locations: the **Architecture section** of [`README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) provides the high-level progressive disclosure model, while the **"What loads when"** section in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) contains the specific table mapping user requests to their corresponding file loads. Both files are located in the `cathrynlavery/diagram-design` repository.