# mermaid-js/mermaid-cli architecture

> Architecture diagram of the GitHub repository mermaid-js/mermaid-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mermaid-js/mermaid-cli
- Repository: https://github.com/mermaid-js/mermaid-cli

## Overview

##### Key Components
- CLI Interface: Located in the “src” directory (files like cli.js, index.js, version.js) that parse command-line arguments, manage option flags (like input/output file paths, themes, custom CSS, config file, etc.), and kick off the rendering process.
- Configuration Management: The project supports various configuration files (puppeteer-config.json, mmd config files) which guide the rendering output (themes, CSS overrides, etc.).
- Testing/CI Pipeline: Display the integration component that includes GitHub workflows and testing scripts (e.g., run-tests.sh, tests in src-test, test-positive, test-negative). This shows how code quality and visual regression testing (like with Percy) is maintained.
- Deployment & Packaging: The Dockerfiles, package.json, and various build scripts (e.g., install-dependencies.sh, scripts/version.js) indicate processes for building, packaging, and releasing the CLI tool.

##### Relationships and Flow
- Testing/CI Pipeline interacting with the source code repository, triggering tests, image comparisons, linting, and deployment steps.
- For the deployment paths, illustrate how Docker serves as an alternative runtime environment, mapping the host’s file system to the container.

##### Architectural Patterns / Design Principles
- Modularization: Different concerns are clearly separated within the codebase (CLI operations, rendering, configuration, etc.).
- Extensibility: Notice how alternative installation options (Docker, NodeJS API, npx) reflect that the architecture is designed to be accessible and extendable.
- Testing & Continuous Integration: The existence of separate test directories and GitHub workflows shows an emphasis on CI/CD and automated testing.
- Command Pattern: The use of a CLI that interprets commands and dispatches to different modules/components.

##### Capturing the Complete Architecture
- Input & Interaction: CLI (parsing command line, accepting file inputs, optional Pipe/STDIN usage).
- Output: File Generation (SVG/PNG/PDF output based on user’s configuration).
- Configuration & Customization: Config Manager (managing theme, CSS files, and optional custom configs).
- Auxiliary Systems: Testing Suite, CI pipelines (GitHub Actions workflows), Docker container support.
- External Integration: Optional Node.JS API pathway.
- Notes on how each component fits into the overall flow from command initiation to file generation.

##### Final Advice
- Maintain simplicity but also be detailed: the more modular you break down the architecture, the easier it becomes for other engineers to understand the roles of different parts.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% User Interaction
    UI["User Commands/API Calls"]:::user

    %% CLI Layer
    subgraph "CLI Layer"
        subgraph "CLI Components"
            CLI_cli["CLI Interface Component"]:::cliComp
            CLI_index["CLI Interface Component"]:::cliComp
            CLI_version["CLI Interface Component"]:::cliComp
        end
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        Config["Configuration Manager"]:::core
        RE["Rendering Engine"]:::core
        FileIO["File I/O Module"]:::core
    end

    %% External Libraries used by Rendering Engine
    subgraph "External Libraries"
        Puppeteer["Puppeteer & Mermaid Libraries"]:::external
    end

    %% Testing & CI Pipeline
    subgraph "Testing & CI Pipeline"
        CI["Testing/CI Pipeline"]:::ci
        subgraph "CI Components"
            CI_wf["Workflows (.github/workflows)"]:::ci
            CI_test["Test Runner (run-tests.sh)"]:::ci
            CI_src["Test Scripts (src-test/test.js)"]:::ci
        end
    end

    %% Deployment & Packaging
    subgraph "Deployment & Packaging"
        Deploy["Deployment Module"]:::deploy
        subgraph "Deployment Components"
            Dep_Dockerfile["Dockerfile"]:::deploy
            Dep_DockerfileBuild["DockerfileBuild"]:::deploy
            Dep_install["install-dependencies.sh"]:::deploy
            Dep_package["package.json"]:::deploy
            Dep_scriptsVer["scripts/version.js"]:::deploy
        end
    end

    %% Alternative API Usage
    subgraph "Alternative API"
        API["Node.js API Entry Point"]:::api
    end

    %% Configuration Files within Configuration Manager
    subgraph "Configuration Files"
        Config1["puppeteer-config.json"]:::configFile
        Config2["test-negative/config.json"]:::configFile
        Config3["test-negative/puppeteerTimeoutConfig.json"]:::configFile
        Config4["test-positive/config.json"]:::configFile
        Config5["config-deterministic.json"]:::configFile
        Config6["config-noUseMaxWidth.json"]:::configFile
    end

    %% Connections
    UI -->|"Initiate command/API call"| CLI_cli
    UI -->|"Direct API call"| API

    CLI_cli -->|"Parse options"| Config
    CLI_cli -->|"Read input files"| FileIO
    CLI_cli -->|"Invoke rendering"| RE

    Config -->|"Provide settings"| RE
    FileIO -->|"Supply diagram data"| RE
    RE -->|"Generate image outputs"| FileIO

    RE -->|"Utilizes"| Puppeteer

    %% CI Interaction (Testing touches core modules)
    CI -->|"Tests CLI & Core Processing"| CLI_cli
    CI -->|"Tests Rendering and Config"| RE
    CI -->|"Validates File I/O"| FileIO

    %% Deployment is triggered after CI completes
    CI -->|"Deploy build"| Deploy

    %% API entry point also leverages CLI processing
    API -->|"Uses CLI modules for processing"| CLI_index

    %% Click Events for CLI Components
    click CLI_cli "https://github.com/mermaid-js/mermaid-cli/blob/master/src/cli.js"
    click CLI_index "https://github.com/mermaid-js/mermaid-cli/blob/master/src/index.js"
    click CLI_version "https://github.com/mermaid-js/mermaid-cli/blob/master/src/version.js"

    %% Click Event for Rendering Engine configuration
    click Config1 "https://github.com/mermaid-js/mermaid-cli/blob/master/puppeteer-config.json"

    %% Click Events for Configuration Management Files
    click Config2 "https://github.com/mermaid-js/mermaid-cli/blob/master/test-negative/config.json"
    click Config3 "https://github.com/mermaid-js/mermaid-cli/blob/master/test-negative/puppeteerTimeoutConfig.json"
    click Config4 "https://github.com/mermaid-js/mermaid-cli/blob/master/test-positive/config.json"
    click Config5 "https://github.com/mermaid-js/mermaid-cli/blob/master/config-deterministic.json"
    click Config6 "https://github.com/mermaid-js/mermaid-cli/blob/master/config-noUseMaxWidth.json"

    %% Click Events for Testing/CI Pipeline Components
    click CI_wf "https://github.com/mermaid-js/mermaid-cli/tree/master/.github/workflows"
    click CI_test "https://github.com/mermaid-js/mermaid-cli/blob/master/run-tests.sh"
    click CI_src "https://github.com/mermaid-js/mermaid-cli/blob/master/src-test/test.js"

    %% Click Events for Deployment & Packaging Components
    click Dep_Dockerfile "https://github.com/mermaid-js/mermaid-cli/tree/master/Dockerfile"
    click Dep_DockerfileBuild "https://github.com/mermaid-js/mermaid-cli/tree/master/DockerfileBuild"
    click Dep_install "https://github.com/mermaid-js/mermaid-cli/blob/master/install-dependencies.sh"
    click Dep_package "https://github.com/mermaid-js/mermaid-cli/blob/master/package.json"
    click Dep_scriptsVer "https://github.com/mermaid-js/mermaid-cli/blob/master/scripts/version.js"

    %% Click Event for Alternative API Usage
    click API "https://github.com/mermaid-js/mermaid-cli/blob/master/src/index.js"

    %% Styles
    classDef user fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef cliComp fill:#2A9D8F,stroke:#264653,stroke-width:2px;
    classDef core fill:#E9C46A,stroke:#F4A261,stroke-width:2px;
    classDef external fill:#264653,stroke:#2A9D8F,stroke-width:2px,color:#ffffff;
    classDef ci fill:#E76F51,stroke:#264653,stroke-width:2px;
    classDef deploy fill:#457B9D,stroke:#264653,stroke-width:2px,color:#ffffff;
    classDef api fill:#A8DADC,stroke:#457B9D,stroke-width:2px;
    classDef configFile fill:#8ecae6,stroke:#219ebc,stroke-width:2px;
```
