# veelenga/claude-mermaid architecture

> Architecture diagram of the GitHub repository veelenga/claude-mermaid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/veelenga/claude-mermaid
- Repository: https://github.com/veelenga/claude-mermaid

## Overview

##### Project type and purpose
- It integrates with Claude Code (and any MCP-compatible client) to provide two tools: `mermaid_preview` (browser live-preview) and `mermaid_save` (export to SVG/PNG/PDF).

##### File structure
- Top-level plugin metadata:
- .claude-plugin/plugin.json & marketplace.json → metadata for Claude Code plugin system
- .mcp.json, .npmignore, tsconfig.json, vitest.config.ts, GitHub/workflows CI files
- src/ (core application code)
- index.ts – MCP CLI entrypoint & command router
- handlers.ts – implements the two MCP tools (`mermaid_preview`, `mermaid_save`)
- live-server.ts – combined HTTP + WebSocket server for live-reload
- page-renderer.ts + src/preview static assets – HTML/CSS/JS for the browser UI
- types.ts & constants.ts
- test/ – unit and integration tests for each module
- start-server.js – helper to launch server standalone

##### README for additional insights
- Ports 3737–3747 for HTTP/WebSocket live reload
- Persistent working files + logs under user’s config directory
- Two MCP tools defined, with their parameters and behaviors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% MCP Client
    subgraph "MCP Client"
        MCPClient["MCP Client\n(Claude Code, etc)"]:::external
    end

    %% CLI Process
    subgraph "CLI Process"
        PluginJSON[".claude-plugin/plugin.json"]:::cli
        PluginMarketplace[".claude-plugin/marketplace.json"]:::cli
        MCPConfig[".mcp.json"]:::cli
        Index["index.ts\nEntry & Router"]:::cli
        Handlers["handlers.ts\nMCP Tools"]:::cli
        DiagramService["diagram-service.ts\nRendering Service"]:::cli
        FileUtils["file-utils.ts\nFile Storage Manager"]:::cli
        Logger["logger.ts\nLogger"]:::cli
        Types["types.ts"]:::cli
        Consts["constants.ts"]:::cli
        Skill["SKILL.md\nBuilt-in Skill"]:::cli
        StartServer["start-server.js\nStandalone Launcher"]:::cli
    end

    %% Live Preview Server
    subgraph "Live Preview Server"
        LiveServer["live-server.ts\nHTTP+WebSocket Server"]:::server
        Routes["routes.ts\nHTTP Routes"]:::server
        PageRenderer["page-renderer.ts\nWeb UI Renderer"]:::server
        subgraph "Static Assets"
            GalleryHTML["gallery.html"]:::server
            TemplateHTML["template.html"]:::server
            StyleCSS["style.css"]:::server
            SharedCSS["shared.css"]:::server
            GalleryCSS["gallery.css"]:::server
            ScriptJS["script.js"]:::server
            GalleryJS["gallery.js"]:::server
        end
    end

    %% Browser Client
    subgraph "Browser Client"
        Browser["Web Browser"]:::external
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        WorkingFiles["~/.config/claude-mermaid/live"]:::storage
        LogsPersist["~/.config/claude-mermaid/logs"]:::storage
    end

    %% External Dependencies
    Puppeteer["Puppeteer\nHeadless Chromium"]:::external
    MermaidJS["Mermaid.js"]:::external

    %% Connections
    MCPClient -->|"STDIO/MCP"| Index
    Index --> Handlers
    Index --> Skill
    Handlers -->|"writes code"| FileUtils
    Handlers -->|"invokes"| DiagramService
    Handlers -->|"spawns if needed"| LiveServer
    Handlers --> Logger
    Handlers --> StartServer
    DiagramService -->|"Puppeteer API"| Puppeteer
    DiagramService --> FileUtils
    DiagramService --> Logger
    FileUtils --> WorkingFiles
    Logger --> LogsPersist
    StartServer --> LiveServer
    LiveServer --> Routes
    LiveServer --> PageRenderer
    LiveServer --> GalleryHTML
    LiveServer --> TemplateHTML
    LiveServer --> StyleCSS
    LiveServer --> SharedCSS
    LiveServer --> GalleryCSS
    LiveServer --> ScriptJS
    LiveServer --> GalleryJS
    FileUtils ---|"FS watch"| LiveServer
    LiveServer -->|"WebSocket"| Browser
    Browser -->|"HTTP"| Routes
    PageRenderer --> Browser
    Routes -->|"HTTP"| Browser
    MermaidJS -.-> DiagramService

    %% Click Events
    click PluginJSON "https://github.com/veelenga/claude-mermaid/blob/main/.claude-plugin/plugin.json"
    click PluginMarketplace "https://github.com/veelenga/claude-mermaid/blob/main/.claude-plugin/marketplace.json"
    click MCPConfig "https://github.com/veelenga/claude-mermaid/blob/main/.mcp.json"
    click Index "https://github.com/veelenga/claude-mermaid/blob/main/src/index.ts"
    click Handlers "https://github.com/veelenga/claude-mermaid/blob/main/src/handlers.ts"
    click DiagramService "https://github.com/veelenga/claude-mermaid/blob/main/src/diagram-service.ts"
    click FileUtils "https://github.com/veelenga/claude-mermaid/blob/main/src/file-utils.ts"
    click Logger "https://github.com/veelenga/claude-mermaid/blob/main/src/logger.ts"
    click Types "https://github.com/veelenga/claude-mermaid/blob/main/src/types.ts"
    click Consts "https://github.com/veelenga/claude-mermaid/blob/main/src/constants.ts"
    click Skill "https://github.com/veelenga/claude-mermaid/blob/main/skills/mermaid-diagrams/SKILL.md"
    click StartServer "https://github.com/veelenga/claude-mermaid/blob/main/start-server.js"
    click LiveServer "https://github.com/veelenga/claude-mermaid/blob/main/src/live-server.ts"
    click Routes "https://github.com/veelenga/claude-mermaid/blob/main/src/routes.ts"
    click PageRenderer "https://github.com/veelenga/claude-mermaid/blob/main/src/page-renderer.ts"
    click GalleryHTML "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/gallery.html"
    click TemplateHTML "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/template.html"
    click StyleCSS "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/style.css"
    click SharedCSS "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/shared.css"
    click GalleryCSS "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/gallery.css"
    click ScriptJS "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/script.js"
    click GalleryJS "https://github.com/veelenga/claude-mermaid/blob/main/src/preview/gallery.js"

    %% Styles
    classDef cli fill:#e0f7fa,stroke:#006064
    classDef server fill:#e8f5e9,stroke:#1b5e20
    classDef storage fill:#fff3e0,stroke:#e65100
    classDef external fill:#eceff1,stroke:#607d8b
```
