The Four Distinct Layers in the Diagram Design System Architecture

The Diagram Design tool implements a clean, four-stage stack comprising the CLI/Command Layer, Diagram-Design Skill Layer, Renderer/Export Layer, and Plugin/Integration Layer, each isolating specific concerns within the cathrynlavery/diagram-design repository.

The cathrynlavery/diagram-design repository structures its functionality as a modular, extensible system that separates user interaction, business logic, rendering, and third-party extensions into discrete architectural tiers. Understanding these four distinct layers is essential for developers seeking to extend the tool's capabilities, debug the rendering pipeline, or integrate custom visual primitives without modifying core logic.

1. CLI / Command Layer (Entry Point)

The CLI / Command Layer serves as the user-facing façade, parsing requests and routing sub-commands to appropriate handlers. This thin entry point captures input arguments and delegates execution to downstream layers while remaining agnostic of diagram logic or rendering specifics.

In the repository, this layer lives in the commands/ directory and includes specialized handlers such as import-mermaid, export-diagram, and doctor. Each command operates as a discrete module, ensuring that CLI concerns remain separated from the core diagram-generation engine.

2. Diagram-Design Skill Layer (Core Logic)

The Diagram-Design Skill Layer functions as the heart of the system, determining which semantic pattern to apply, selecting appropriate visual types, and constructing the internal representation of the diagram. This layer encapsulates the domain expertise that translates abstract concepts into structured diagram models.

According to the source code, the primary logic resides in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), specifically within the "Architecture" entry that drives the entire workflow. This markdown-based skill definition orchestrates how incoming data gets interpreted and transformed into a structured intermediate format before rendering occurs.

3. Renderer / Export Layer (Artifact Generation)

The Renderer / Export Layer converts the internal model into concrete, distributable artifacts such as HTML, SVG, and PNG files. This deterministic pipeline writes generated assets adjacent to source files, ensuring that outputs remain synchronized with their originating diagrams.

Implementation details are found in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md), which defines the export command specifications. The layer also leverages accompanying asset templates located at path patterns like assets/example-*.html to standardize output formatting across different diagram types.

4. Plugin / Integration Layer (Extensibility)

The Plugin / Integration Layer provides an optional extensibility mechanism that enriches diagrams with external resources—such as icons, brand tokens, and custom primitives—without requiring modifications to core logic. This layer follows an adapter pattern, loading extensions dynamically based on directory presence.

Plugin implementations reside in directories like /.factory-plugin/, alongside analogous folders such as .codex-plugin and .claude-plugin. These isolated extension points allow teams to inject proprietary styling or organizational-specific visual elements while maintaining the integrity of the base architecture.

Summary

The four distinct layers in the Diagram Design system architecture create a robust separation of concerns that balances usability with extensibility:

• CLI / Command Layer: Handles user input and command routing via the commands/ directory
• Diagram-Design Skill Layer: Manages semantic logic and internal model construction through SKILL.md
• Renderer / Export Layer: Transforms models into concrete files using export-diagram.md and template assets
• Plugin / Integration Layer: Supports optional extensions via .factory-plugin/ and related plugin directories

This modular stack ensures that developers can modify rendering pipelines, add new CLI commands, or inject custom branding without destabilizing the core diagram-generation engine.

Frequently Asked Questions

How does the CLI layer route commands to the appropriate handler?

The CLI layer parses user input in the commands/ directory, where discrete modules like import-mermaid and export-diagram register their specific argument patterns. Each command operates independently, delegating actual diagram processing to the Skill Layer while remaining responsible only for input validation and initial routing.

What file contains the core logic for determining diagram structure?

The core logic resides in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), specifically within the "Architecture" entry. This file drives the workflow by deciding which semantic patterns apply to incoming data and selecting the appropriate visual representation type before passing the structured model to the Renderer Layer.

Where does the system store export templates for HTML and other formats?

Export templates and rendering specifications are defined in [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md), with accompanying template assets following the assets/example-*.html naming pattern. These templates provide the structural scaffolding that the Renderer Layer uses when converting internal models into distributable files.

Can I add custom icons or brand elements without modifying the core code?

Yes, the Plugin Layer supports this through directories like /.factory-plugin/, .codex-plugin/, and .claude-plugin/. Place custom primitives, icon sets, or brand tokens in these folders to enrich diagram outputs. The system loads these extensions dynamically, allowing you to customize visual appearances without touching the Skill or Renderer layers.

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