# mermaid-js/mermaid architecture

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

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

## Overview

Mermaid turns Markdown-inspired diagram text into rendered diagrams; its README describes this author-to-result workflow and broad diagramming purpose. The graph groups the core runtime, diagram implementations, rendering/layout machinery, and companion editor and packages. Source excerpts expose diagram registration, editor wiring, and selected internal calls; other subsystem links are included only where documented, and unsampled internals are represented at directory level.

Main entry points: [`packages/mermaid/src/mermaidAPI.ts`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/mermaidAPI.ts) (Mermaid API), [`packages/mermaid-local-editor/static/app.js`](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/app.js) (Local Editor), [`packages/mermaid/src/diagrams`](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/diagrams) (Diagram Implementations), [`packages/parser/src/parse.ts`](https://github.com/mermaid-js/mermaid/blob/develop/packages/parser/src/parse.ts) (Parser Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Mermaid Runtime"]
  node_mermaid["Mermaid API<br/>[mermaidAPI.ts]"]
  node_orchestration["Diagram Registry"]
  node_config["Configuration<br/>[config.type.ts]"]
  node_common["Shared Diagram Data"]
end

subgraph group_diagrams["Diagram Types"]
  node_diagramtypes["Diagram Implementations"]
  node_gitparser["Git Graph Parser<br/>[gitGraphParser.ts]"]
  node_gitast["Git Graph AST<br/>[gitGraphAst.ts]"]
  node_usecaseparser["Use Case Parser<br/>[usecase.parser.ts]"]
  node_wardleyparser["Wardley Parser<br/>[wardleyParser.ts]"]
  node_parser["Parser Package<br/>[parse.ts]"]
end

subgraph group_render["Rendering And Layout"]
  node_renderer["Diagram Rendering"]
  node_layout["Shared Layout Utilities"]
  node_swimlane["Swimlane Layout<br/>[pipeline.ts]"]
  node_router["Orthogonal Router<br/>[router.ts]"]
  node_xychart["XY Chart Builder<br/>[orchestrator.ts]"]
  node_tidytree["Tidy Tree Layout<br/>[layout.ts]"]
end

subgraph group_extras["Editor And Extensions"]
  node_editor["Local Editor<br/>[app.js]"]
  node_editorstorage[("Diagram Storage<br/>[storage.js]")]
  node_editorrenderer["Editor Preview<br/>[renderer.js]"]
  node_example["Example Diagram"]
  node_zenuml["ZenUML Extension<br/>[zenumlRenderer.ts]"]
end

node_author(("Diagram Author"))
node_output["Rendered Diagram"]

node_author -->|"provides text"| node_mermaid
node_mermaid -.->|"selects diagram"| node_orchestration
node_orchestration -->|"registers detectors"| node_diagramtypes
node_mermaid -->|"renders diagrams"| node_output
node_diagramtypes -->|"renders"| node_renderer
node_gitparser -->|"uses parser package"| node_parser
node_wardleyparser -->|"uses parser package"| node_parser
node_gitparser -->|"uses AST"| node_gitast
node_usecaseparser -->|"uses tokens"| node_parser
node_diagramtypes -.->|"shares diagram data"| node_common
node_renderer -.->|"uses layout"| node_layout
node_swimlane -.->|"routes edges"| node_router
node_editor -->|"persists diagrams"| node_editorstorage
node_editor -->|"renders preview"| node_editorrenderer
node_editor -.->|"initializes runtime"| node_mermaid
node_xychart -.->|"provides components"| node_renderer
node_tidytree -.->|"provides layout"| node_layout

click node_mermaid "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/mermaidAPI.ts"
click node_orchestration "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagram-api/diagram-orchestration.ts"
click node_config "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/config.type.ts"
click node_common "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/common/populateCommonDb.ts"
click node_diagramtypes "https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/diagrams"
click node_gitparser "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/git/gitGraphParser.ts"
click node_gitast "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/git/gitGraphAst.ts"
click node_usecaseparser "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/usecase/parser/usecase.parser.ts"
click node_wardleyparser "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/wardley/wardleyParser.ts"
click node_parser "https://github.com/mermaid-js/mermaid/blob/develop/packages/parser/src/parse.ts"
click node_renderer "https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/diagrams"
click node_layout "https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/rendering-util/layout-algorithms"
click node_swimlane "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/pipeline.ts"
click node_router "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/orthogonalRouter/router.ts"
click node_xychart "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/xychart/chartBuilder/orchestrator.ts"
click node_tidytree "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-layout-tidy-tree/src/layout.ts"
click node_editor "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/app.js"
click node_editorstorage "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/js/storage.js"
click node_editorrenderer "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/js/renderer.js"
click node_example "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-example-diagram/src/exampleDiagramRenderer.js"
click node_zenuml "https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-zenuml/src/zenumlRenderer.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mermaid,node_orchestration,node_config,node_common toneBlue
class node_diagramtypes,node_gitparser,node_gitast,node_usecaseparser,node_wardleyparser,node_parser toneAmber
class node_renderer,node_layout,node_swimlane,node_router,node_xychart,node_tidytree toneMint
class node_editor,node_editorstorage,node_editorrenderer,node_example,node_zenuml toneRose
class node_author,node_output toneIndigo
```

## Components

### Mermaid Runtime

- [Mermaid API](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/mermaidAPI.ts): `packages/mermaid/src/mermaidAPI.ts`
- [Diagram Registry](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagram-api/diagram-orchestration.ts): `packages/mermaid/src/diagram-api/diagram-orchestration.ts`
- [Configuration](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/config.type.ts): `packages/mermaid/src/config.type.ts`
- [Shared Diagram Data](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/common/populateCommonDb.ts): `packages/mermaid/src/diagrams/common/populateCommonDb.ts`

### Diagram Types

- [Diagram Implementations](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/diagrams): `packages/mermaid/src/diagrams`
- [Git Graph Parser](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/git/gitGraphParser.ts): `packages/mermaid/src/diagrams/git/gitGraphParser.ts`
- [Git Graph AST](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/git/gitGraphAst.ts): `packages/mermaid/src/diagrams/git/gitGraphAst.ts`
- [Use Case Parser](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/usecase/parser/usecase.parser.ts): `packages/mermaid/src/diagrams/usecase/parser/usecase.parser.ts`
- [Wardley Parser](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/wardley/wardleyParser.ts): `packages/mermaid/src/diagrams/wardley/wardleyParser.ts`
- [Parser Package](https://github.com/mermaid-js/mermaid/blob/develop/packages/parser/src/parse.ts): `packages/parser/src/parse.ts`

### Rendering And Layout

- [Diagram Rendering](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/diagrams): `packages/mermaid/src/diagrams`
- [Shared Layout Utilities](https://github.com/mermaid-js/mermaid/tree/develop/packages/mermaid/src/rendering-util/layout-algorithms): `packages/mermaid/src/rendering-util/layout-algorithms`
- [Swimlane Layout](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/pipeline.ts): `packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/pipeline.ts`
- [Orthogonal Router](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/orthogonalRouter/router.ts): `packages/mermaid/src/rendering-util/layout-algorithms/swimlanes/orthogonalRouter/router.ts`
- [XY Chart Builder](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid/src/diagrams/xychart/chartBuilder/orchestrator.ts): `packages/mermaid/src/diagrams/xychart/chartBuilder/orchestrator.ts`
- [Tidy Tree Layout](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-layout-tidy-tree/src/layout.ts): `packages/mermaid-layout-tidy-tree/src/layout.ts`

### Editor And Extensions

- [Local Editor](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/app.js): `packages/mermaid-local-editor/static/app.js`
- [Diagram Storage](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/js/storage.js): `packages/mermaid-local-editor/static/js/storage.js`
- [Editor Preview](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-local-editor/static/js/renderer.js): `packages/mermaid-local-editor/static/js/renderer.js`
- [Example Diagram](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-example-diagram/src/exampleDiagramRenderer.js): `packages/mermaid-example-diagram/src/exampleDiagramRenderer.js`
- [ZenUML Extension](https://github.com/mermaid-js/mermaid/blob/develop/packages/mermaid-zenuml/src/zenumlRenderer.ts): `packages/mermaid-zenuml/src/zenumlRenderer.ts`

### Other components

- **Diagram Author**
- **Rendered Diagram**

## Connections

- Diagram Author → Mermaid API: provides text (evidence: `README.md`)
- Mermaid API → Diagram Registry: selects diagram
- Diagram Registry → Diagram Implementations: registers detectors (evidence: `packages/mermaid/src/diagram-api/diagram-orchestration.ts`)
- Mermaid API → Rendered Diagram: renders diagrams (evidence: `README.md`)
- Diagram Implementations → Diagram Rendering: renders (evidence: `README.md`)
- Git Graph Parser → Parser Package: uses parser package (evidence: `packages/mermaid/src/diagrams/git/gitGraphParser.ts`)
- Wardley Parser → Parser Package: uses parser package (evidence: `packages/mermaid/src/diagrams/wardley/wardleyParser.ts`)
- Git Graph Parser → Git Graph AST: uses AST (evidence: `packages/mermaid/src/diagrams/git/gitGraphParser.ts`)
- Use Case Parser → Parser Package: uses tokens (evidence: `packages/mermaid/src/diagrams/usecase/parser/usecase.parser.ts`)
- Diagram Implementations → Shared Diagram Data: shares diagram data (evidence: `packages/mermaid/src/diagrams/wardley/wardleyParser.ts`)
- Diagram Rendering → Shared Layout Utilities: uses layout
- Swimlane Layout → Orthogonal Router: routes edges
- Local Editor → Diagram Storage: persists diagrams (evidence: `packages/mermaid-local-editor/static/app.js`)
- Local Editor → Editor Preview: renders preview (evidence: `packages/mermaid-local-editor/static/app.js`)
- Local Editor → Mermaid API: initializes runtime
- XY Chart Builder → Diagram Rendering: provides components (evidence: `packages/mermaid/src/diagrams/xychart/chartBuilder/orchestrator.ts`)
- Tidy Tree Layout → Shared Layout Utilities: provides layout
