docs: diagrams plugin tooling (#5741)

* added plugin * updated plugin + added component * dummy data TO BE REMOVED * (wip) workflow generator tool * add workflow generator tooling * updated the generator tool * added code file creation * fix design of diagrams * configured diagram theme * added build script * removed comments + unnecessary files * general fixes * refactored plugin * added README + more output types
2023-11-28 14:30:23 +00:00
parent d27b86ab8e
commit fa4935259c
19 changed files with 2961 additions and 167 deletions
--- a/docs-util/packages/workflows-diagrams-generator/README.md
+++ b/docs-util/packages/workflows-diagrams-generator/README.md
@@ -0,0 +1,52 @@
+# Workflows Diagram Generator
+
+An internal tool to generate [Mermaid](https://mermaid.js.org/) diagrams for workflows.
+
+> Note: This tool is a beta tool created to generate diagrams that can be used in the Medusa documentation.
+
+## Usage
+
+After installing the dependencies, run the following command:
+
+```bash
+yarn start run ./path/to/workflow -o ./path/to/output/dir
+```
+
+Where:
+
+- `./path/to/workflow` is the path to a file containing a Workflow, or a directory containing more than one file.
+- `./path/to/output/dir` is the path to the directory that outputted diagrams should be placed in.
+
+### Command Options
+
+#### --t, --type
+
+```bash
+yarn start run ./path/to/workflow -o ./path/to/output/dir -t markdown
+```
+
+The `type` of diagram to be generated. It can be one of the following:
+
+- `docs` (default): For each workflow, it creates a directory holding the diagram of the workflow and its code in separate files. Diagrams are placed in `.mermaid` files.
+- `markdown`: Generates the diagram of each workflow in a `.md` file.
+- `mermaid`: Generates the diagram of each workflow in a `.mermaid` file.
+- `console`: Outputs the diagrams in the console.
+- `svg`: Generates the diagram in SVG format.
+- `png`: Generates the diagram in PNG format.
+- `pdf`: Generates the diagram in PDF format.
+
+#### --no-theme
+
+```bash
+yarn start run ./path/to/workflow -o ./path/to/output/dir --no-theme
+```
+
+Removes Medusa's default theming from the outputted diagram. Note that Medusa's theme doesn't support dark mode.
+
+#### --pretty-names
+
+```bash
+yarn start run ./path/to/workflow -o ./path/to/output/dir --pretty-names
+```
+
+Changes slug and camel-case names of steps to capitalized names.
--- a/docs-util/packages/workflows-diagrams-generator/package.json
+++ b/docs-util/packages/workflows-diagrams-generator/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "workflows-diagram-generator",
+  "license": "MIT",
+  "scripts": {
+    "start": "ts-node src/index.ts",
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "prepublishOnly": "cross-env NODE_ENV=production tsc --build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.0.0",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "bin": {
+    "workflow-diagrams-generator": "dist/index.js"
+  },
+  "dependencies": {
+    "@medusajs/workflows-sdk": "latest",
+    "@mermaid-js/mermaid-cli": "^10.6.1",
+    "commander": "^11.1.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.1.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.9.4"
+  }
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/classes/diagram-builder.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/classes/diagram-builder.ts
@@ -0,0 +1,210 @@
+import { TransactionStepsDefinition } from "@medusajs/orchestration"
+import getRandomString from "../utils/get-random-string.js"
+
+type DiagramBuilderOptions = {
+  theme?: boolean
+  prettyNames?: boolean
+}
+
+type ReturnedSteps = {
+  escapedStepNames: string[]
+  links: string[]
+  defsStr: string
+}
+
+export default class DiagramBuilder {
+  private options: DiagramBuilderOptions
+  static SPACING = "\t"
+
+  constructor(options: DiagramBuilderOptions) {
+    this.options = options
+  }
+
+  buildDiagram(workflow: TransactionStepsDefinition): string {
+    let diagram = `${this.getThemeConfig()}${
+      this.options.theme ? this.getLinePrefix(1) : ""
+    }flowchart TB`
+
+    const stepsDiagram = this.getSteps(workflow, this.options.theme ? 2 : 1)
+
+    diagram +=
+      stepsDiagram.defsStr + `\n` + this.formatLinks(stepsDiagram.links)
+
+    return diagram
+  }
+
+  getThemeConfig(): string {
+    return this.options.theme
+      ? `%%{
+      init: {
+        'theme': 'base',
+        'themeVariables': {
+          'background': '#FFFFFF',
+          'mainBkg': '#FFFFFF',
+          'primaryColor': '#FFFFFF',
+          'primaryTextColor': '#030712',
+          'primaryBorderColor': '#D1D5DB',
+          'nodeBorder': '#D1D5DB',
+          'lineColor': '#11181C',
+          'fontFamily': 'Inter',
+          'fontSize': '13px',
+          'tertiaryColor': '#F3F4F6',
+          'tertiaryBorderColor': '#D1D5DB',
+          'tertiaryTextColor': '#030712'
+        }
+      }
+    }%%`
+      : ""
+  }
+
+  getSteps(
+    flow: TransactionStepsDefinition | TransactionStepsDefinition[],
+    level: number
+  ): ReturnedSteps {
+    const links: string[] = []
+    let defsStr = ""
+    const escapedStepNames: string[] = []
+    const linePrefix = this.getLinePrefix(level)
+
+    const flowArr: TransactionStepsDefinition[] | undefined = Array.isArray(
+      flow
+    )
+      ? flow
+      : !flow.action && Array.isArray(flow.next)
+        ? flow.next
+        : undefined
+
+    if (flowArr) {
+      // these are steps running in parallel
+      // since there are changes where the flowArr contains
+      // one item, we check the length before treating the
+      // main steps as steps running in parallel
+      const areStepsParallel = flowArr.length > 1
+      const parallelDefinitions: Record<string, string> = {}
+      flowArr.forEach((flowItem) => {
+        const flowSteps = this.getSteps(flowItem, level)
+        if (areStepsParallel) {
+          const escapedName = this.getEscapedStepName(flowItem.action)
+          if (escapedName) {
+            const itemDefinition = `${linePrefix}${escapedName}(${this.formatStepName(
+              flowItem.action!
+            )})`
+            parallelDefinitions[itemDefinition] = flowSteps.defsStr.replace(
+              itemDefinition,
+              ""
+            )
+          } else {
+            // if the step doesn't have an action name
+            // we just show it as a regular step rather than
+            // a subgraph
+            defsStr += `${linePrefix}${flowSteps.defsStr}`
+          }
+        } else {
+          // if the steps aren't parallel
+          // just show them as regular steps
+          defsStr += `${linePrefix}${flowSteps.defsStr}`
+        }
+        links.push(...flowSteps.links)
+        escapedStepNames.push(...flowSteps.escapedStepNames)
+      })
+
+      // if there are steps in parallel,
+      // we show them as a subgraph
+      const definitionKeys = Object.keys(parallelDefinitions)
+      if (definitionKeys.length) {
+        defsStr += `${this.getSubgraph(
+          definitionKeys.join(""),
+          linePrefix
+        )}${linePrefix}${Object.values(parallelDefinitions).join("")}`
+      }
+    } else {
+      const flowItem = flow as TransactionStepsDefinition
+      const escapedName = this.getEscapedStepName(flowItem.action)
+
+      if (escapedName.length) {
+        escapedStepNames.push(escapedName)
+        defsStr += `${linePrefix}${escapedName}(${this.formatStepName(
+          flowItem.action!
+        )})`
+      }
+
+      if (flowItem.next) {
+        const nextSteps = this.getSteps(flowItem.next, level)
+        defsStr += `${linePrefix}${nextSteps.defsStr}`
+        if (escapedName.length) {
+          nextSteps.escapedStepNames.forEach((escapedStep) => {
+            links.push(`${linePrefix}${escapedName} --> ${escapedStep}`)
+          })
+        } else {
+          escapedStepNames.push(...nextSteps.escapedStepNames)
+        }
+        links.push(...nextSteps.links)
+      }
+    }
+
+    return {
+      escapedStepNames,
+      links,
+      defsStr,
+    }
+  }
+
+  getSubgraph(defsStr: string, linePrefix: string): string {
+    return `${linePrefix}subgraph parallel${getRandomString()} [Parallel]${linePrefix}${defsStr}${linePrefix}end`
+  }
+
+  getEscapedStepName(originalName: string | undefined): string {
+    return originalName?.replaceAll("-", "") || ""
+  }
+
+  formatStepName(originalName: string): string {
+    if (!this.options?.prettyNames) {
+      return originalName
+    }
+    return originalName
+      .replaceAll("-", " ")
+      .replaceAll(/([A-Z])/g, " $1")
+      .split(" ")
+      .map((word) => `${word.charAt(0).toUpperCase()}${word.substring(1)}`)
+      .join(" ")
+  }
+
+  getLinePrefix(indentation = 0): string {
+    return `\n${DiagramBuilder.SPACING.repeat(indentation)}`
+  }
+
+  // TODO need to explore with this function
+  // for now it just returns the joined links, but
+  // it should split links on multiple lines in the
+  // diagram
+  formatLinks(links: string[], level = 2): string {
+    const linePrefix = this.getLinePrefix(level)
+    return links.join(linePrefix)
+
+    // This is used to ensure that a line doesn't get too long
+    // let nodesInCurrentLine = 0
+    // // TODO change this to be a command line option
+    // const maxNodesInLine = 3
+
+    // if (links.length <= maxNodesInLine) {
+    //   return links.join(linePrefix)
+    // }
+
+    // let finalStr = ""
+
+    // links.forEach((link) => {
+    //   if (nodesInCurrentLine === 0) {
+    //     finalStr += "subgraph"
+    //   }
+
+    //   finalStr += link
+    //   ++nodesInCurrentLine
+    //   if (nodesInCurrentLine === maxNodesInLine) {
+    //     finalStr += "end"
+    //     nodesInCurrentLine = 0
+    //   }
+    // })
+
+    // return finalStr
+  }
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/commands/generate.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/commands/generate.ts
@@ -0,0 +1,83 @@
+/* eslint-disable no-case-declarations */
+import { WorkflowManager } from "@medusajs/orchestration"
+import * as path from "path"
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "fs"
+import registerWorkflows from "../utils/register-workflows.js"
+import DiagramBuilder from "../classes/diagram-builder.js"
+import { run as runMermaid } from "@mermaid-js/mermaid-cli"
+
+type Options = {
+  output: string
+  type: "docs" | "markdown" | "mermaid" | "console" | "svg" | "png" | "pdf"
+  theme: boolean
+  prettyNames: boolean
+}
+
+export default async function (workflowPath: string, options: Options) {
+  const workflowDefinitions = await registerWorkflows(workflowPath)
+
+  const diagramBuilder = new DiagramBuilder(options)
+
+  if (
+    workflowDefinitions.size > 0 &&
+    ["svg", "png", "pdf"].includes(options.type)
+  ) {
+    console.log(
+      `Generating ${options.type} file(s) with mermaid. This may take some time...`
+    )
+  }
+
+  for (const [name, code] of workflowDefinitions) {
+    const workflow = WorkflowManager.getWorkflow(name)
+
+    if (!workflow) {
+      continue
+    }
+
+    const diagram = diagramBuilder.buildDiagram(workflow.flow_)
+    if (!existsSync(options.output)) {
+      mkdirSync(options.output, { recursive: true })
+    }
+
+    switch (options.type) {
+      case "docs":
+        const workflowPath = path.join(options.output, name)
+        if (!existsSync(workflowPath)) {
+          mkdirSync(workflowPath, { recursive: true })
+        }
+        // write files
+        writeFileSync(path.join(workflowPath, "diagram.mermaid"), diagram)
+        if (code) {
+          writeFileSync(path.join(workflowPath, "code.ts"), code)
+        }
+        break
+      case "mermaid":
+        writeFileSync(path.join(options.output, `${name}.mermaid`), diagram)
+        break
+      case "markdown":
+        writeFileSync(
+          path.join(options.output, `${name}.md`),
+          `\`\`\`mermaid\n${diagram}\n\`\`\``
+        )
+        break
+      case "console":
+        console.log(`Diagram for workflow ${name}:\n${diagram}`)
+        break
+      case "svg":
+      case "png":
+      case "pdf":
+        const tempFilePath = path.join(options.output, `${name}.mermaid`)
+        writeFileSync(tempFilePath, diagram)
+        await runMermaid(
+          tempFilePath,
+          path.join(options.output, `${name}.${options.type}`),
+          {
+            quiet: true,
+          }
+        )
+        rmSync(tempFilePath)
+    }
+  }
+
+  console.log(`Generated diagrams for ${workflowDefinitions.size} workflows.`)
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/index.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/index.ts
@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Command, Option } from "commander"
+import generate from "./commands/generate.js"
+
+const program = new Command()
+
+program
+  .name("workflows-diagram-generator")
+  .description("Generate diagram(s) for workflow(s).")
+
+program
+  .command("run")
+  .description(
+    "Generate Mermaid.js diagrams for your workflows based on the type you choose."
+  )
+  .argument(
+    "<workflowPath>",
+    "The path to a workflow file or a directory of workflow files."
+  )
+  .requiredOption(
+    "-o, --output <output>",
+    "The directory to output the files in."
+  )
+  .addOption(
+    new Option("-t, --type <type>", "Type of diagrams to be generated.")
+      .choices(["docs", "markdown", "mermaid", "console", "svg", "png", "pdf"])
+      .default("docs")
+  )
+  .option("--no-theme", "Remove theming from outputted diagrams.", true)
+  .option(
+    "--pretty-names",
+    "Prettify step names. Useful for creating presentational diagrams.",
+    false
+  )
+  .action(generate)
+
+program.parse()
--- a/docs-util/packages/workflows-diagrams-generator/src/utils/escape-str.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/utils/escape-str.ts
@@ -0,0 +1,3 @@
+export default function (str: string): string {
+  return str.replaceAll(`"`, "#quot;").replaceAll("-", "&ndash;")
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/utils/formatting.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/utils/formatting.ts
@@ -0,0 +1,5 @@
+export const SPACING = "\t"
+
+export function getLinePrefix(indentation = 0): string {
+  return `\n${SPACING.repeat(indentation)}`
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/utils/get-random-string.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/utils/get-random-string.ts
@@ -0,0 +1,12 @@
+export default function (length = 4) {
+  let result = ""
+  const characters =
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+  const charactersLength = characters.length
+  let counter = 0
+  while (counter < length) {
+    result += characters.charAt(Math.floor(Math.random() * charactersLength))
+    counter += 1
+  }
+  return result
+}
--- a/docs-util/packages/workflows-diagrams-generator/src/utils/register-workflows.ts
+++ b/docs-util/packages/workflows-diagrams-generator/src/utils/register-workflows.ts
@@ -0,0 +1,79 @@
+import { statSync, readFileSync } from "fs"
+import * as glob from "glob"
+import path from "path"
+import { fileURLToPath } from "url"
+
+type FileInfo = {
+  workflowId: string
+  code: string
+}
+
+export default async function (
+  workflowPath: string
+): Promise<Map<string, string>> {
+  const workflowDefinitions = new Map<string, string>()
+  const fileStat = statSync(workflowPath)
+  if (fileStat.isFile()) {
+    const fileInfo = await importFile(workflowPath)
+    if (fileInfo.workflowId.length && fileInfo.code.length) {
+      workflowDefinitions.set(fileInfo.workflowId, fileInfo.code)
+    }
+  } else {
+    const files = glob.sync(`${workflowPath}/**/*.{ts,js}`, {})
+    await Promise.all(
+      files.map(async (file) => {
+        const fileInfo = await importFile(file)
+        if (fileInfo.workflowId.length && fileInfo.code.length) {
+          workflowDefinitions.set(fileInfo.workflowId, fileInfo.code)
+        }
+      })
+    )
+  }
+
+  return workflowDefinitions
+}
+
+function getRelativeImportPath(filePath: string) {
+  const __filename = fileURLToPath(import.meta.url)
+  return path.relative(path.dirname(__filename), filePath)
+}
+
+async function importFile(filePath: string): Promise<FileInfo> {
+  const fileInfo: FileInfo = {
+    workflowId: "",
+    code: "",
+  }
+
+  const relativeFilePath = getRelativeImportPath(filePath)
+  const imported = await import(relativeFilePath)
+
+  fileInfo.code = readFileSync(filePath, "utf-8")
+
+  if (imported.default) {
+    switch (typeof imported.default) {
+      case "function":
+        fileInfo.workflowId = getWorkflowName(imported.default) || ""
+        break
+      case "object":
+        Object.values(imported.default).find((exportedVariable: unknown) => {
+          fileInfo.workflowId = getWorkflowName(exportedVariable) || ""
+          return fileInfo.workflowId.length !== 0
+        })
+    }
+  } else if (typeof imported === "object") {
+    Object.values(imported).find((exportedVariable: unknown) => {
+      fileInfo.workflowId = getWorkflowName(exportedVariable) || ""
+      return fileInfo.workflowId.length !== 0
+    })
+  }
+
+  return fileInfo
+}
+
+function getWorkflowName(variable: unknown): string | undefined {
+  return typeof variable === "function" &&
+    "getName" in variable &&
+    typeof variable.getName === "function"
+    ? variable.getName()
+    : undefined
+}
--- a/docs-util/packages/workflows-diagrams-generator/tsconfig.json
+++ b/docs-util/packages/workflows-diagrams-generator/tsconfig.json
@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "Node16", 
+    "moduleResolution": "node16",
+    "outDir": "./dist", 
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+  },
+  "include": ["src"],
+  "ts-node": {
+    "esm": true,
+    "experimentalSpecifierResolution": "node",
+    "transpileOnly": true
+  }
+}
--- a/docs-util/yarn.lock
+++ b/docs-util/yarn.lock
--- a/www/apps/docs/docusaurus.config.js
+++ b/www/apps/docs/docusaurus.config.js
@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 import "dotenv/config"
 import fs from "fs"
+import path from "path"
 import { themes as prismThemes } from "prism-react-renderer"
 const reverseSidebarItems = require("./src/utils/reverse-sidebar")
 const excludeSidebarResults = require("./src/utils/exclude-sidebar-results")
@@ -24,6 +25,7 @@ const config = {
      admonitions: false,
      headingIds: false,
    },
+    mermaid: true,
  },
  plugins: [
    require.resolve("docusaurus-plugin-image-zoom"),
@@ -62,8 +64,39 @@ const config = {
        },
      }
    },
+    [
+      "./src/plugins/docusaurus-plugin-diagram2code-showcase",
+      {
+        directoryPath: path.join(__dirname, "diagrams"),
+        outputPath: path.join(__dirname, "src", "utils"),
+      },
+    ],
  ],
+  themes: ["@docusaurus/theme-mermaid"],
  themeConfig: {
+    mermaid: {
+      theme: {
+        light: "base",
+        dark: "base",
+      },
+      options: {
+        themeVariables: {
+          background: "#FFFFFF",
+          mainBkg: "#FFFFFF",
+          primaryColor: "#FFFFFF",
+          primaryTextColor: "#030712",
+          primaryBorderColor: "#D1D5DB",
+          nodeBorder: "#D1D5DB",
+          lineColor: "#11181C",
+          fontFamily: "Inter",
+          fontSize: "13px",
+          tertiaryColor: "#F3F4F6",
+          tertiaryBorderColor: "#D1D5DB",
+          tertiaryTextColor: "#030712",
+          clusterBkg: "#F3F4F6",
+        },
+      },
+    },
    image: "img/docs-meta.jpg",
    colorMode: {
      defaultMode: "light",
--- a/www/apps/docs/package.json
+++ b/www/apps/docs/package.json
@@ -15,7 +15,8 @@
    "write-translations": "docusaurus write-translations",
    "write-heading-ids": "docusaurus write-heading-ids",
    "lint": "eslint --ext .js,.jsx,.ts,.tsx . --fix",
-    "lint:content": "eslint --no-eslintrc -c .content.eslintrc.js content --fix"
+    "lint:content": "eslint --no-eslintrc -c .content.eslintrc.js content --fix",
+    "diagram2code:generate": "docusaurus diagram2code:generate"
  },
  "dependencies": {
    "@babel/preset-react": "^7.18.6",
@@ -24,6 +25,7 @@
    "@docusaurus/core": "3.0.0",
    "@docusaurus/preset-classic": "3.0.0",
    "@docusaurus/remark-plugin-npm2yarn": "3.0.0",
+    "@docusaurus/theme-mermaid": "^3.0.0",
    "@mdx-js/react": "3",
    "@medusajs/icons": "^1.0.0",
    "@svgr/webpack": "6.2.1",
--- a/www/apps/docs/src/components/Diagram2CodeSpecs/index.tsx
+++ b/www/apps/docs/src/components/Diagram2CodeSpecs/index.tsx
@@ -0,0 +1,53 @@
+import React from "react"
+import { Diagram2CodeSpec } from "@medusajs/docs"
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+import { specs } from "../../utils/specs"
+import CodeBlock from "../../theme/CodeBlock"
+import Mermaid from "@docusaurus/theme-mermaid/lib/theme/Mermaid/index.js"
+
+type WorkflowReferenceProps = {
+  specName: string
+}
+
+const Diagram2CodeSpecs = ({ specName }: WorkflowReferenceProps) => {
+  if (!Object.hasOwn(specs, specName)) {
+    return <></>
+  }
+  const specsData: Diagram2CodeSpec = specs[specName]
+
+  const transformTitle = (title: string): string => {
+    return title
+      .split("-")
+      .map((word) => `${word.charAt(0).toUpperCase()}${word.substring(1)}`)
+      .join(" ")
+  }
+
+  return (
+    <>
+      {!Object.keys(specsData).length && <span>No diagrams found</span>}
+      {Object.entries(specsData).map(([name, diagram2code]) => (
+        <React.Fragment key={name}>
+          <h2>{transformTitle(name)}</h2>
+          <Tabs groupId="workflows">
+            <TabItem
+              value="diagram"
+              label="Diagram"
+              default
+              className="bg-diagrams bg-repeat rounded [&>div]:flex [&>div]:justify-center [&>div]:items-center"
+            >
+              <Mermaid value={diagram2code.diagram} />
+            </TabItem>
+            {diagram2code.code && (
+              <TabItem value="code" label="Code">
+                <CodeBlock language="ts">{diagram2code.code}</CodeBlock>
+              </TabItem>
+            )}
+          </Tabs>
+        </React.Fragment>
+      ))}
+    </>
+  )
+}
+
+export default Diagram2CodeSpecs
--- a/www/apps/docs/src/plugins/docusaurus-plugin-diagram2code-showcase/index.js
+++ b/www/apps/docs/src/plugins/docusaurus-plugin-diagram2code-showcase/index.js
@@ -0,0 +1,119 @@
+import { exec } from "child_process"
+import { Dirent } from "fs"
+import { readdir, readFile, writeFile } from "fs/promises"
+import path from "path"
+
+export default async function docusaurusPluginDiagram2codeShowcase(
+  context,
+  { directoryPath, outputPath, debug = false }
+) {
+  async function readIfExists(filePath) {
+    try {
+      return await readFile(filePath, "utf-8")
+    } catch (e) {
+      if (debug) {
+        console.error(
+          `[Diagram2Code Showcase Plugin] An error occurred while reading ${filePath}: ${e}`
+        )
+      }
+      return null
+    }
+  }
+
+  async function generateSpecs() {
+    let specs = {}
+    let diagramSpecDirectories = []
+
+    try {
+      // read files under the provided directory path
+      diagramSpecDirectories = (
+        await readdir(directoryPath, { withFileTypes: true })
+      ).filter((dirent) => dirent.isDirectory())
+    } catch {
+      console.error(
+        `Directory ${directoryPath} doesn't exist. Skipping reading diagrams...`
+      )
+      return
+    }
+
+    await Promise.all(
+      diagramSpecDirectories.map(async (dirent) => {
+        const tempSpecs = {}
+        const specsPath = path.join(directoryPath, dirent.name)
+
+        const specDirents = (
+          await readdir(specsPath, { withFileTypes: true })
+        ).filter((specDirent) => specDirent.isDirectory())
+        await Promise.all(
+          specDirents.map(async (specDirent) => {
+            const specPath = path.join(specsPath, specDirent.name)
+            // read the diagram and code files
+            const diagram = await readIfExists(
+              path.join(specPath, "diagram.mermaid")
+            )
+            const code =
+              (await readIfExists(path.join(specPath, "code.ts"))) ||
+              (await readIfExists(path.join(specPath, "code.tsx"))) ||
+              (await readIfExists(path.join(specPath, "code.js")))
+
+            if (!diagram) {
+              return
+            }
+
+            tempSpecs[specDirent.name] = {
+              diagram,
+              code,
+            }
+          })
+        )
+
+        if (Object.keys(tempSpecs).length) {
+          specs[dirent.name] = tempSpecs
+        }
+      })
+    )
+
+    // order steps alphabetically
+    specs = Object.keys(specs)
+      .sort()
+      .reduce((accumulator, key) => {
+        accumulator[key] = specs[key]
+
+        return accumulator
+      }, {})
+
+    // store specs in a JavaScript object that can be consumed
+    const specOutputFilePath = path.join(outputPath, "specs.ts")
+    await writeFile(
+      specOutputFilePath,
+      `export const specs = ${JSON.stringify(specs, null, "\t")}`
+    )
+
+    // execute eslint
+    exec(`eslint ${specOutputFilePath} --fix`)
+
+    return specOutputFilePath
+  }
+
+  return {
+    name: "docusaurus-plugin-diagram2code-showcase",
+    async loadContent() {
+      await generateSpecs()
+    },
+    extendCli(cli) {
+      cli
+        .command("diagram2code:generate")
+        .description(
+          "Generate the spec file used to create diagram-to-code showcase"
+        )
+        .action(async () => {
+          const specFile = await generateSpecs()
+          // eslint-disable-next-line no-console
+          console.log(`Generated diagram2code spec file at ${specFile}`)
+        })
+    },
+    getPathsToWatch() {
+      return [directoryPath]
+    },
+  }
+}
--- a/www/apps/docs/src/types/index.d.ts
+++ b/www/apps/docs/src/types/index.d.ts
@@ -207,4 +207,17 @@ declare module "@medusajs/docs" {
  export declare type MedusaDocusaurusContext = DocusaurusContext & {
    siteConfig: MedusaDocusaurusConfig
  }
+
+  export declare type Diagram2Code = {
+    diagram: string
+    code: string
+  }
+
+  export declare type Diagram2CodeSpec = {
+    [k: string]: Diagram2Code
+  }
+
+  export declare type Diagram2CodeSpecs = {
+    [k: string]: Diagram2CodeSpec
+  }
 }
--- a/www/apps/docs/static/img/diagrams-bg.png
+++ b/www/apps/docs/static/img/diagrams-bg.png
--- a/www/packages/tailwind/base.tailwind.config.js
+++ b/www/packages/tailwind/base.tailwind.config.js
@@ -260,6 +260,7 @@ module.exports = {
        fade: "linear-gradient(to top, rgba(255, 255, 255, 1), rgba(255, 255, 255, 0))",
        "fade-dark":
          "linear-gradient(to top, rgba(27, 27, 31, 1), rgba(27, 27, 31, 0))",
+        diagrams: "url('/img/diagrams-bg.png')",
      }),
      screens: {
        xs: "576px",
--- a/www/yarn.lock
+++ b/www/yarn.lock
@@ -2673,6 +2673,13 @@ __metadata:
  languageName: node
  linkType: hard

+"@braintree/sanitize-url@npm:^6.0.1":
+  version: 6.0.4
+  resolution: "@braintree/sanitize-url@npm:6.0.4"
+  checksum: 5d7bac57f3e49931db83f65aaa4fd22f96caa323bf0c7fcf6851fdbed179a8cf29eaa5dd372d340fc51ca5f44345ea5bc0196b36c8b16179888a7c9044313420
+  languageName: node
+  linkType: hard
+
 "@cloudinary/html@npm:^1.11.2":
  version: 1.11.2
  resolution: "@cloudinary/html@npm:1.11.2"
@@ -3326,6 +3333,24 @@ __metadata:
  languageName: node
  linkType: hard

+"@docusaurus/theme-mermaid@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "@docusaurus/theme-mermaid@npm:3.0.0"
+  dependencies:
+    "@docusaurus/core": 3.0.0
+    "@docusaurus/module-type-aliases": 3.0.0
+    "@docusaurus/theme-common": 3.0.0
+    "@docusaurus/types": 3.0.0
+    "@docusaurus/utils-validation": 3.0.0
+    mermaid: ^10.4.0
+    tslib: ^2.6.0
+  peerDependencies:
+    react: ^18.0.0
+    react-dom: ^18.0.0
+  checksum: 50c6f262aca35f02b480474c6e20a2b527af06cfbb0fb83b2467909aa8c0132292ca20ead761d66ac05d8f01d120d47e008bf4239102521530b5ae485f580198
+  languageName: node
+  linkType: hard
+
 "@docusaurus/theme-search-algolia@npm:3.0.0":
  version: 3.0.0
  resolution: "@docusaurus/theme-search-algolia@npm:3.0.0"
@@ -7897,6 +7922,29 @@ __metadata:
  languageName: node
  linkType: hard

+"@types/d3-scale-chromatic@npm:^3.0.0":
+  version: 3.0.3
+  resolution: "@types/d3-scale-chromatic@npm:3.0.3"
+  checksum: 2f48c6f370edba485b57b73573884ded71914222a4580140ff87ee96e1d55ccd05b1d457f726e234a31269b803270ac95d5554229ab6c43c7e4a9894e20dd490
+  languageName: node
+  linkType: hard
+
+"@types/d3-scale@npm:^4.0.3":
+  version: 4.0.8
+  resolution: "@types/d3-scale@npm:4.0.8"
+  dependencies:
+    "@types/d3-time": "*"
+  checksum: 57de90e4016f640b83cb960b7e3a0ab3ed02e720898840ddc5105264ffcfea73336161442fdc91895377c2d2f91904d637282f16852b8535b77e15a761c8e99e
+  languageName: node
+  linkType: hard
+
+"@types/d3-time@npm:*":
+  version: 3.0.3
+  resolution: "@types/d3-time@npm:3.0.3"
+  checksum: 245a8aadca504df27edf730de502e47a68f16ae795c86b5ca35e7afa91c133aa9ef4d08778f8cf1ed2be732f89a4105ba4b437ce2afbdfd17d3d937b6ba5f568
+  languageName: node
+  linkType: hard
+
 "@types/debug@npm:^4.0.0":
  version: 4.1.8
  resolution: "@types/debug@npm:4.1.8"
@@ -10306,6 +10354,13 @@ __metadata:
  languageName: node
  linkType: hard

+"commander@npm:7, commander@npm:^7.2.0":
+  version: 7.2.0
+  resolution: "commander@npm:7.2.0"
+  checksum: 8d690ff13b0356df7e0ebbe6c59b4712f754f4b724d4f473d3cc5b3fdcf978e3a5dc3078717858a2ceb50b0f84d0660a7f22a96cdc50fb877d0c9bb31593d23a
+  languageName: node
+  linkType: hard
+
 "commander@npm:^10.0.0":
  version: 10.0.1
  resolution: "commander@npm:10.0.1"
@@ -10334,13 +10389,6 @@ __metadata:
  languageName: node
  linkType: hard

-"commander@npm:^7.2.0":
-  version: 7.2.0
-  resolution: "commander@npm:7.2.0"
-  checksum: 8d690ff13b0356df7e0ebbe6c59b4712f754f4b724d4f473d3cc5b3fdcf978e3a5dc3078717858a2ceb50b0f84d0660a7f22a96cdc50fb877d0c9bb31593d23a
-  languageName: node
-  linkType: hard
-
 "commander@npm:^8.3.0":
  version: 8.3.0
  resolution: "commander@npm:8.3.0"
@@ -10588,6 +10636,24 @@ __metadata:
  languageName: node
  linkType: hard

+"cose-base@npm:^1.0.0":
+  version: 1.0.3
+  resolution: "cose-base@npm:1.0.3"
+  dependencies:
+    layout-base: ^1.0.0
+  checksum: a6e400b1d101393d6af0967c1353355777c1106c40417c5acaef6ca8bdda41e2fc9398f466d6c85be30290943ad631f2590569f67b3fd5368a0d8318946bd24f
+  languageName: node
+  linkType: hard
+
+"cose-base@npm:^2.2.0":
+  version: 2.2.0
+  resolution: "cose-base@npm:2.2.0"
+  dependencies:
+    layout-base: ^2.0.0
+  checksum: 14b9f8100ac322a00777ffb1daeb3321af368bbc9cabe3103943361273baee2003202ffe38e4ab770960b600214224e9c196195a78d589521540aa694df7cdec
+  languageName: node
+  linkType: hard
+
 "cosmiconfig@npm:^6.0.0":
  version: 6.0.0
  resolution: "cosmiconfig@npm:6.0.0"
@@ -10916,6 +10982,401 @@ __metadata:
  languageName: node
  linkType: hard

+"cytoscape-cose-bilkent@npm:^4.1.0":
+  version: 4.1.0
+  resolution: "cytoscape-cose-bilkent@npm:4.1.0"
+  dependencies:
+    cose-base: ^1.0.0
+  peerDependencies:
+    cytoscape: ^3.2.0
+  checksum: 5e2480ddba9da1a68e700ed2c674cbfd51e9efdbd55788f1971a68de4eb30708e3b3a5e808bf5628f7a258680406bbe6586d87a9133e02a9bdc1ab1a92f512f2
+  languageName: node
+  linkType: hard
+
+"cytoscape-fcose@npm:^2.1.0":
+  version: 2.2.0
+  resolution: "cytoscape-fcose@npm:2.2.0"
+  dependencies:
+    cose-base: ^2.2.0
+  peerDependencies:
+    cytoscape: ^3.2.0
+  checksum: ce472c9f85b9057e75c5685396f8e1f2468895e71b184913e05ad56dcf3092618fe59a1054f29cb0995051ba8ebe566ad0dd49a58d62845145624bd60cd44917
+  languageName: node
+  linkType: hard
+
+"cytoscape@npm:^3.23.0":
+  version: 3.27.0
+  resolution: "cytoscape@npm:3.27.0"
+  dependencies:
+    heap: ^0.2.6
+    lodash: ^4.17.21
+  checksum: 89cf57de58fe9742a31466198f32d527d7aead8537bb72538712fc3cf029aeacb90a4721f9a42f5f19fed72d71929f04676711d6c37634c0c156782b7377d858
+  languageName: node
+  linkType: hard
+
+"d3-array@npm:1 - 2":
+  version: 2.12.1
+  resolution: "d3-array@npm:2.12.1"
+  dependencies:
+    internmap: ^1.0.0
+  checksum: 7eca10427a9f113a4ca6a0f7301127cab26043fd5e362631ef5a0edd1c4b2dd70c56ed317566700c31e4a6d88b55f3951aaba192291817f243b730cb2352882e
+  languageName: node
+  linkType: hard
+
+"d3-array@npm:2 - 3, d3-array@npm:2.10.0 - 3, d3-array@npm:2.5.0 - 3, d3-array@npm:3, d3-array@npm:^3.2.0":
+  version: 3.2.4
+  resolution: "d3-array@npm:3.2.4"
+  dependencies:
+    internmap: 1 - 2
+  checksum: 08b95e91130f98c1375db0e0af718f4371ccacef7d5d257727fe74f79a24383e79aba280b9ffae655483ffbbad4fd1dec4ade0119d88c4749f388641c8bf8c50
+  languageName: node
+  linkType: hard
+
+"d3-axis@npm:3":
+  version: 3.0.0
+  resolution: "d3-axis@npm:3.0.0"
+  checksum: a271e70ba1966daa5aaf6a7f959ceca3e12997b43297e757c7b945db2e1ead3c6ee226f2abcfa22abbd4e2e28bd2b71a0911794c4e5b911bbba271328a582c78
+  languageName: node
+  linkType: hard
+
+"d3-brush@npm:3":
+  version: 3.0.0
+  resolution: "d3-brush@npm:3.0.0"
+  dependencies:
+    d3-dispatch: 1 - 3
+    d3-drag: 2 - 3
+    d3-interpolate: 1 - 3
+    d3-selection: 3
+    d3-transition: 3
+  checksum: 07baf00334c576da2f68a91fc0da5732c3a5fa19bd3d7aed7fd24d1d674a773f71a93e9687c154176f7246946194d77c48c2d8fed757f5dcb1a4740067ec50a8
+  languageName: node
+  linkType: hard
+
+"d3-chord@npm:3":
+  version: 3.0.1
+  resolution: "d3-chord@npm:3.0.1"
+  dependencies:
+    d3-path: 1 - 3
+  checksum: baa6013914af3f4fe1521f0d16de31a38eb8a71d08ff1dec4741f6f45a828661e5cd3935e39bd14e3032bdc78206c283ca37411da21d46ec3cfc520be6e7a7ce
+  languageName: node
+  linkType: hard
+
+"d3-color@npm:1 - 3, d3-color@npm:3":
+  version: 3.1.0
+  resolution: "d3-color@npm:3.1.0"
+  checksum: a4e20e1115fa696fce041fbe13fbc80dc4c19150fa72027a7c128ade980bc0eeeba4bcf28c9e21f0bce0e0dbfe7ca5869ef67746541dcfda053e4802ad19783c
+  languageName: node
+  linkType: hard
+
+"d3-contour@npm:4":
+  version: 4.0.2
+  resolution: "d3-contour@npm:4.0.2"
+  dependencies:
+    d3-array: ^3.2.0
+  checksum: 98bc5fbed6009e08707434a952076f39f1cd6ed8b9288253cc3e6a3286e4e80c63c62d84954b20e64bf6e4ededcc69add54d3db25e990784a59c04edd3449032
+  languageName: node
+  linkType: hard
+
+"d3-delaunay@npm:6":
+  version: 6.0.4
+  resolution: "d3-delaunay@npm:6.0.4"
+  dependencies:
+    delaunator: 5
+  checksum: 57c3aecd2525664b07c4c292aa11cf49b2752c0cf3f5257f752999399fe3c592de2d418644d79df1f255471eec8057a9cc0c3062ed7128cb3348c45f69597754
+  languageName: node
+  linkType: hard
+
+"d3-dispatch@npm:1 - 3, d3-dispatch@npm:3":
+  version: 3.0.1
+  resolution: "d3-dispatch@npm:3.0.1"
+  checksum: 6eca77008ce2dc33380e45d4410c67d150941df7ab45b91d116dbe6d0a3092c0f6ac184dd4602c796dc9e790222bad3ff7142025f5fd22694efe088d1d941753
+  languageName: node
+  linkType: hard
+
+"d3-drag@npm:2 - 3, d3-drag@npm:3":
+  version: 3.0.0
+  resolution: "d3-drag@npm:3.0.0"
+  dependencies:
+    d3-dispatch: 1 - 3
+    d3-selection: 3
+  checksum: d2556e8dc720741a443b595a30af403dd60642dfd938d44d6e9bfc4c71a962142f9a028c56b61f8b4790b65a34acad177d1263d66f103c3c527767b0926ef5aa
+  languageName: node
+  linkType: hard
+
+"d3-dsv@npm:1 - 3, d3-dsv@npm:3":
+  version: 3.0.1
+  resolution: "d3-dsv@npm:3.0.1"
+  dependencies:
+    commander: 7
+    iconv-lite: 0.6
+    rw: 1
+  bin:
+    csv2json: bin/dsv2json.js
+    csv2tsv: bin/dsv2dsv.js
+    dsv2dsv: bin/dsv2dsv.js
+    dsv2json: bin/dsv2json.js
+    json2csv: bin/json2dsv.js
+    json2dsv: bin/json2dsv.js
+    json2tsv: bin/json2dsv.js
+    tsv2csv: bin/dsv2dsv.js
+    tsv2json: bin/dsv2json.js
+  checksum: 10e6af9e331950ed258f34ab49ac1b7060128ef81dcf32afc790bd1f7e8c3cc2aac7f5f875250a83f21f39bb5925fbd0872bb209f8aca32b3b77d32bab8a65ab
+  languageName: node
+  linkType: hard
+
+"d3-ease@npm:1 - 3, d3-ease@npm:3":
+  version: 3.0.1
+  resolution: "d3-ease@npm:3.0.1"
+  checksum: fec8ef826c0cc35cda3092c6841e07672868b1839fcaf556e19266a3a37e6bc7977d8298c0fcb9885e7799bfdcef7db1baaba9cd4dcf4bc5e952cf78574a88b0
+  languageName: node
+  linkType: hard
+
+"d3-fetch@npm:3":
+  version: 3.0.1
+  resolution: "d3-fetch@npm:3.0.1"
+  dependencies:
+    d3-dsv: 1 - 3
+  checksum: 4f467a79bf290395ac0cbb5f7562483f6a18668adc4c8eb84c9d3eff048b6f6d3b6f55079ba1ebf1908dabe000c941d46be447f8d78453b2dad5fb59fb6aa93b
+  languageName: node
+  linkType: hard
+
+"d3-force@npm:3":
+  version: 3.0.0
+  resolution: "d3-force@npm:3.0.0"
+  dependencies:
+    d3-dispatch: 1 - 3
+    d3-quadtree: 1 - 3
+    d3-timer: 1 - 3
+  checksum: 220a16a1a1ac62ba56df61028896e4b52be89c81040d20229c876efc8852191482c233f8a52bb5a4e0875c321b8e5cb6413ef3dfa4d8fe79eeb7d52c587f52cf
+  languageName: node
+  linkType: hard
+
+"d3-format@npm:1 - 3, d3-format@npm:3":
+  version: 3.1.0
+  resolution: "d3-format@npm:3.1.0"
+  checksum: 049f5c0871ebce9859fc5e2f07f336b3c5bfff52a2540e0bac7e703fce567cd9346f4ad1079dd18d6f1e0eaa0599941c1810898926f10ac21a31fd0a34b4aa75
+  languageName: node
+  linkType: hard
+
+"d3-geo@npm:3":
+  version: 3.1.0
+  resolution: "d3-geo@npm:3.1.0"
+  dependencies:
+    d3-array: 2.5.0 - 3
+  checksum: 5b0a26d232787ca9e824a660827c28626a51004328dde7c76a1bd300d3cad8c7eeb55fea64c8cd6495d5a34fea434fb1418d59926a6cb24e6fb6e2b6f62c6bd9
+  languageName: node
+  linkType: hard
+
+"d3-hierarchy@npm:3":
+  version: 3.1.2
+  resolution: "d3-hierarchy@npm:3.1.2"
+  checksum: 6dcdb480539644aa7fc0d72dfc7b03f99dfbcdf02714044e8c708577e0d5981deb9d3e99bbbb2d26422b55bcc342ac89a0fa2ea6c9d7302e2fc0951dd96f89cf
+  languageName: node
+  linkType: hard
+
+"d3-interpolate@npm:1 - 3, d3-interpolate@npm:1.2.0 - 3, d3-interpolate@npm:3":
+  version: 3.0.1
+  resolution: "d3-interpolate@npm:3.0.1"
+  dependencies:
+    d3-color: 1 - 3
+  checksum: 19f4b4daa8d733906671afff7767c19488f51a43d251f8b7f484d5d3cfc36c663f0a66c38fe91eee30f40327443d799be17169f55a293a3ba949e84e57a33e6a
+  languageName: node
+  linkType: hard
+
+"d3-path@npm:1":
+  version: 1.0.9
+  resolution: "d3-path@npm:1.0.9"
+  checksum: e35e84df5abc18091f585725b8235e1fa97efc287571585427d3a3597301e6c506dea56b11dfb3c06ca5858b3eb7f02c1bf4f6a716aa9eade01c41b92d497eb5
+  languageName: node
+  linkType: hard
+
+"d3-path@npm:1 - 3, d3-path@npm:3, d3-path@npm:^3.1.0":
+  version: 3.1.0
+  resolution: "d3-path@npm:3.1.0"
+  checksum: dc1d58ec87fa8319bd240cf7689995111a124b141428354e9637aa83059eb12e681f77187e0ada5dedfce346f7e3d1f903467ceb41b379bfd01cd8e31721f5da
+  languageName: node
+  linkType: hard
+
+"d3-polygon@npm:3":
+  version: 3.0.1
+  resolution: "d3-polygon@npm:3.0.1"
+  checksum: e236aa7f33efa9a4072907af7dc119f85b150a0716759d4fe5f12f62573018264a6cbde8617fbfa6944a7ae48c1c0c8d3f39ae72e11f66dd471e9b5e668385df
+  languageName: node
+  linkType: hard
+
+"d3-quadtree@npm:1 - 3, d3-quadtree@npm:3":
+  version: 3.0.1
+  resolution: "d3-quadtree@npm:3.0.1"
+  checksum: 18302d2548bfecaef788152397edec95a76400fd97d9d7f42a089ceb68d910f685c96579d74e3712d57477ed042b056881b47cd836a521de683c66f47ce89090
+  languageName: node
+  linkType: hard
+
+"d3-random@npm:3":
+  version: 3.0.1
+  resolution: "d3-random@npm:3.0.1"
+  checksum: 987a1a1bcbf26e6cf01fd89d5a265b463b2cea93560fc17d9b1c45e8ed6ff2db5924601bcceb808de24c94133f000039eb7fa1c469a7a844ccbf1170cbb25b41
+  languageName: node
+  linkType: hard
+
+"d3-sankey@npm:^0.12.3":
+  version: 0.12.3
+  resolution: "d3-sankey@npm:0.12.3"
+  dependencies:
+    d3-array: 1 - 2
+    d3-shape: ^1.2.0
+  checksum: 261debb01a13269f6fc53b9ebaef174a015d5ad646242c23995bf514498829ab8b8f920a7873724a7494288b46bea3ce7ebc5a920b745bc8ae4caa5885cf5204
+  languageName: node
+  linkType: hard
+
+"d3-scale-chromatic@npm:3":
+  version: 3.0.0
+  resolution: "d3-scale-chromatic@npm:3.0.0"
+  dependencies:
+    d3-color: 1 - 3
+    d3-interpolate: 1 - 3
+  checksum: 920a80f2e31b5686798c116e99d1671c32f55fb60fa920b742aa4ac5175b878c615adb4e55a246d65367e6e1061fdbcc55807be731fb5b18ae628d1df62bfac1
+  languageName: node
+  linkType: hard
+
+"d3-scale@npm:4":
+  version: 4.0.2
+  resolution: "d3-scale@npm:4.0.2"
+  dependencies:
+    d3-array: 2.10.0 - 3
+    d3-format: 1 - 3
+    d3-interpolate: 1.2.0 - 3
+    d3-time: 2.1.1 - 3
+    d3-time-format: 2 - 4
+  checksum: 65d9ad8c2641aec30ed5673a7410feb187a224d6ca8d1a520d68a7d6eac9d04caedbff4713d1e8545be33eb7fec5739983a7ab1d22d4e5ad35368c6729d362f1
+  languageName: node
+  linkType: hard
+
+"d3-selection@npm:2 - 3, d3-selection@npm:3":
+  version: 3.0.0
+  resolution: "d3-selection@npm:3.0.0"
+  checksum: e59096bbe8f0cb0daa1001d9bdd6dbc93a688019abc97d1d8b37f85cd3c286a6875b22adea0931b0c88410d025563e1643019161a883c516acf50c190a11b56b
+  languageName: node
+  linkType: hard
+
+"d3-shape@npm:3":
+  version: 3.2.0
+  resolution: "d3-shape@npm:3.2.0"
+  dependencies:
+    d3-path: ^3.1.0
+  checksum: f1c9d1f09926daaf6f6193ae3b4c4b5521e81da7d8902d24b38694517c7f527ce3c9a77a9d3a5722ad1e3ff355860b014557b450023d66a944eabf8cfde37132
+  languageName: node
+  linkType: hard
+
+"d3-shape@npm:^1.2.0":
+  version: 1.3.7
+  resolution: "d3-shape@npm:1.3.7"
+  dependencies:
+    d3-path: 1
+  checksum: 548057ce59959815decb449f15632b08e2a1bdce208f9a37b5f98ec7629dda986c2356bc7582308405ce68aedae7d47b324df41507404df42afaf352907577ae
+  languageName: node
+  linkType: hard
+
+"d3-time-format@npm:2 - 4, d3-time-format@npm:4":
+  version: 4.1.0
+  resolution: "d3-time-format@npm:4.1.0"
+  dependencies:
+    d3-time: 1 - 3
+  checksum: 735e00fb25a7fd5d418fac350018713ae394eefddb0d745fab12bbff0517f9cdb5f807c7bbe87bb6eeb06249662f8ea84fec075f7d0cd68609735b2ceb29d206
+  languageName: node
+  linkType: hard
+
+"d3-time@npm:1 - 3, d3-time@npm:2.1.1 - 3, d3-time@npm:3":
+  version: 3.1.0
+  resolution: "d3-time@npm:3.1.0"
+  dependencies:
+    d3-array: 2 - 3
+  checksum: a984f77e1aaeaa182679b46fbf57eceb6ebdb5f67d7578d6f68ef933f8eeb63737c0949991618a8d29472dbf43736c7d7f17c452b2770f8c1271191cba724ca1
+  languageName: node
+  linkType: hard
+
+"d3-timer@npm:1 - 3, d3-timer@npm:3":
+  version: 3.0.1
+  resolution: "d3-timer@npm:3.0.1"
+  checksum: d4c63cb4bb5461d7038aac561b097cd1c5673969b27cbdd0e87fa48d9300a538b9e6f39b4a7f0e3592ef4f963d858c8a9f0e92754db73116770856f2fc04561a
+  languageName: node
+  linkType: hard
+
+"d3-transition@npm:2 - 3, d3-transition@npm:3":
+  version: 3.0.1
+  resolution: "d3-transition@npm:3.0.1"
+  dependencies:
+    d3-color: 1 - 3
+    d3-dispatch: 1 - 3
+    d3-ease: 1 - 3
+    d3-interpolate: 1 - 3
+    d3-timer: 1 - 3
+  peerDependencies:
+    d3-selection: 2 - 3
+  checksum: 4e74535dda7024aa43e141635b7522bb70cf9d3dfefed975eb643b36b864762eca67f88fafc2ca798174f83ca7c8a65e892624f824b3f65b8145c6a1a88dbbad
+  languageName: node
+  linkType: hard
+
+"d3-zoom@npm:3":
+  version: 3.0.0
+  resolution: "d3-zoom@npm:3.0.0"
+  dependencies:
+    d3-dispatch: 1 - 3
+    d3-drag: 2 - 3
+    d3-interpolate: 1 - 3
+    d3-selection: 2 - 3
+    d3-transition: 2 - 3
+  checksum: ee2036479049e70d8c783d594c444fe00e398246048e3f11a59755cd0e21de62ece3126181b0d7a31bf37bcf32fd726f83ae7dea4495ff86ec7736ce5ad36fd3
+  languageName: node
+  linkType: hard
+
+"d3@npm:^7.4.0, d3@npm:^7.8.2":
+  version: 7.8.5
+  resolution: "d3@npm:7.8.5"
+  dependencies:
+    d3-array: 3
+    d3-axis: 3
+    d3-brush: 3
+    d3-chord: 3
+    d3-color: 3
+    d3-contour: 4
+    d3-delaunay: 6
+    d3-dispatch: 3
+    d3-drag: 3
+    d3-dsv: 3
+    d3-ease: 3
+    d3-fetch: 3
+    d3-force: 3
+    d3-format: 3
+    d3-geo: 3
+    d3-hierarchy: 3
+    d3-interpolate: 3
+    d3-path: 3
+    d3-polygon: 3
+    d3-quadtree: 3
+    d3-random: 3
+    d3-scale: 4
+    d3-scale-chromatic: 3
+    d3-selection: 3
+    d3-shape: 3
+    d3-time: 3
+    d3-time-format: 4
+    d3-timer: 3
+    d3-transition: 3
+    d3-zoom: 3
+  checksum: 408758dcc2437cbff8cd207b9d82760030b5c53c1df6a2ce5b1a76633388a6892fd65c0632cfa83da963e239722d49805062e5fb05d99e0fb078bda14cb22222
+  languageName: node
+  linkType: hard
+
+"dagre-d3-es@npm:7.0.10":
+  version: 7.0.10
+  resolution: "dagre-d3-es@npm:7.0.10"
+  dependencies:
+    d3: ^7.8.2
+    lodash-es: ^4.17.21
+  checksum: 3e1bb6efe9a78cea3fe6ff265eb330692f057bf84c99d6a1d67db379231c37a1a1ca2e1ccc25a732ddf924cd5566062c033d88defd230debec324dc9256c6775
+  languageName: node
+  linkType: hard
+
 "damerau-levenshtein@npm:^1.0.8":
  version: 1.0.8
  resolution: "damerau-levenshtein@npm:1.0.8"
@@ -10950,6 +11411,13 @@ __metadata:
  languageName: node
  linkType: hard

+"dayjs@npm:^1.11.7":
+  version: 1.11.10
+  resolution: "dayjs@npm:1.11.10"
+  checksum: 4de9af50639d47df87f2e15fa36bb07e0f9ed1e9c52c6caa1482788ee9a384d668f1dbd00c54f82aaab163db07d61d2899384b8254da3a9184fc6deca080e2fe
+  languageName: node
+  linkType: hard
+
 "debug@npm:2.6.9, debug@npm:^2.6.0, debug@npm:^2.6.9":
  version: 2.6.9
  resolution: "debug@npm:2.6.9"
@@ -11087,6 +11555,15 @@ __metadata:
  languageName: node
  linkType: hard

+"delaunator@npm:5":
+  version: 5.0.0
+  resolution: "delaunator@npm:5.0.0"
+  dependencies:
+    robust-predicates: ^3.0.0
+  checksum: 8655c1ad12dc58bd6350f882c12065ea415cfc809e4cac12b7b5c4941e981aaabee1afdcf13985dcd545d13d0143eb3805836f50e2b097af8137b204dfbea4f6
+  languageName: node
+  linkType: hard
+
 "delayed-stream@npm:~1.0.0":
  version: 1.0.0
  resolution: "delayed-stream@npm:1.0.0"
@@ -11305,6 +11782,7 @@ __metadata:
    "@docusaurus/module-type-aliases": 3.0.0
    "@docusaurus/preset-classic": 3.0.0
    "@docusaurus/remark-plugin-npm2yarn": 3.0.0
+    "@docusaurus/theme-mermaid": ^3.0.0
    "@docusaurus/tsconfig": 3.0.0
    "@docusaurus/types": 3.0.0
    "@mdx-js/react": 3
@@ -11439,6 +11917,13 @@ __metadata:
  languageName: node
  linkType: hard

+"dompurify@npm:^3.0.5":
+  version: 3.0.6
+  resolution: "dompurify@npm:3.0.6"
+  checksum: defc5126e1724bbe5dd5835f0de838c6dc9726a73fc74893e4c661a3c1bd5c65189295013afee74ae7097b3be93499539ff9ec66118d3aa46e788266b1f7514c
+  languageName: node
+  linkType: hard
+
 "domutils@npm:^2.5.2, domutils@npm:^2.8.0":
  version: 2.8.0
  resolution: "domutils@npm:2.8.0"
@@ -11536,6 +12021,13 @@ __metadata:
  languageName: node
  linkType: hard

+"elkjs@npm:^0.8.2":
+  version: 0.8.2
+  resolution: "elkjs@npm:0.8.2"
+  checksum: 550b48a44143f6d1ac12482b301670a92ac6a685b2f6a0089ee0b66a4037b800890c507b60afd572851d3208e92ff2ed7cc30785e78acb196b422c3abfd20d6f
+  languageName: node
+  linkType: hard
+
 "emoji-regex@npm:^8.0.0":
  version: 8.0.0
  resolution: "emoji-regex@npm:8.0.0"
@@ -13868,6 +14360,13 @@ __metadata:
  languageName: node
  linkType: hard

+"heap@npm:^0.2.6":
+  version: 0.2.7
+  resolution: "heap@npm:0.2.7"
+  checksum: 341c5d51ae13dc8346c371a8a69c57c972fcb9a3233090d3dd5ba29d483d6b5b4e75492443cbfeacd46608bb30e6680f646ffb7a6205900221735587d07a79b6
+  languageName: node
+  linkType: hard
+
 "history@npm:^4.9.0":
  version: 4.10.1
  resolution: "history@npm:4.10.1"
@@ -14163,7 +14662,7 @@ __metadata:
  languageName: node
  linkType: hard

-"iconv-lite@npm:0.6.3, iconv-lite@npm:^0.6.2":
+"iconv-lite@npm:0.6, iconv-lite@npm:0.6.3, iconv-lite@npm:^0.6.2":
  version: 0.6.3
  resolution: "iconv-lite@npm:0.6.3"
  dependencies:
@@ -14344,6 +14843,20 @@ __metadata:
  languageName: node
  linkType: hard

+"internmap@npm:1 - 2":
+  version: 2.0.3
+  resolution: "internmap@npm:2.0.3"
+  checksum: 8cedd57f07bbc22501516fbfc70447f0c6812871d471096fad9ea603516eacc2137b633633daf432c029712df0baefd793686388ddf5737e3ea15074b877f7ed
+  languageName: node
+  linkType: hard
+
+"internmap@npm:^1.0.0":
+  version: 1.0.1
+  resolution: "internmap@npm:1.0.1"
+  checksum: 60942be815ca19da643b6d4f23bd0bf4e8c97abbd080fb963fe67583b60bdfb3530448ad4486bae40810e92317bded9995cc31411218acc750d72cd4e8646eee
+  languageName: node
+  linkType: hard
+
 "interpret@npm:^1.0.0":
  version: 1.4.0
  resolution: "interpret@npm:1.4.0"
@@ -15231,6 +15744,13 @@ __metadata:
  languageName: node
  linkType: hard

+"khroma@npm:^2.0.0":
+  version: 2.1.0
+  resolution: "khroma@npm:2.1.0"
+  checksum: 634d98753ff5d2540491cafeb708fc98de0d43f4e6795256d5c8f6e3ad77de93049ea41433928fda3697adf7bbe6fe27351858f6d23b78f8b5775ef314c59891
+  languageName: node
+  linkType: hard
+
 "kind-of@npm:^6.0.0, kind-of@npm:^6.0.2":
  version: 6.0.3
  resolution: "kind-of@npm:6.0.3"
@@ -15287,6 +15807,20 @@ __metadata:
  languageName: node
  linkType: hard

+"layout-base@npm:^1.0.0":
+  version: 1.0.2
+  resolution: "layout-base@npm:1.0.2"
+  checksum: 2a55d0460fd9f6ed53d7e301b9eb3dea19bda03815d616a40665ce6dc75c1f4d62e1ca19a897da1cfaf6de1b91de59cd6f2f79ba1258f3d7fccc7d46ca7f3337
+  languageName: node
+  linkType: hard
+
+"layout-base@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "layout-base@npm:2.0.1"
+  checksum: a44df9ef3cbff9916a10f616635e22b5787c89fa62b2fec6f99e8e6ee512c7cebd22668ce32dab5a83c934ba0a309c51a678aa0b40d70853de6c357893c0a88b
+  languageName: node
+  linkType: hard
+
 "leven@npm:^3.1.0":
  version: 3.1.0
  resolution: "leven@npm:3.1.0"
@@ -15378,6 +15912,13 @@ __metadata:
  languageName: node
  linkType: hard

+"lodash-es@npm:^4.17.21":
+  version: 4.17.21
+  resolution: "lodash-es@npm:4.17.21"
+  checksum: fb407355f7e6cd523a9383e76e6b455321f0f153a6c9625e21a8827d10c54c2a2341bd2ae8d034358b60e07325e1330c14c224ff582d04612a46a4f0479ff2f2
+  languageName: node
+  linkType: hard
+
 "lodash.camelcase@npm:^4.3.0":
  version: 4.3.0
  resolution: "lodash.camelcase@npm:4.3.0"
@@ -15659,7 +16200,7 @@ __metadata:
  languageName: node
  linkType: hard

-"mdast-util-from-markdown@npm:^1.0.0, mdast-util-from-markdown@npm:^1.1.0":
+"mdast-util-from-markdown@npm:^1.0.0, mdast-util-from-markdown@npm:^1.1.0, mdast-util-from-markdown@npm:^1.3.0":
  version: 1.3.1
  resolution: "mdast-util-from-markdown@npm:1.3.1"
  dependencies:
@@ -16123,6 +16664,34 @@ __metadata:
  languageName: node
  linkType: hard

+"mermaid@npm:^10.4.0":
+  version: 10.6.1
+  resolution: "mermaid@npm:10.6.1"
+  dependencies:
+    "@braintree/sanitize-url": ^6.0.1
+    "@types/d3-scale": ^4.0.3
+    "@types/d3-scale-chromatic": ^3.0.0
+    cytoscape: ^3.23.0
+    cytoscape-cose-bilkent: ^4.1.0
+    cytoscape-fcose: ^2.1.0
+    d3: ^7.4.0
+    d3-sankey: ^0.12.3
+    dagre-d3-es: 7.0.10
+    dayjs: ^1.11.7
+    dompurify: ^3.0.5
+    elkjs: ^0.8.2
+    khroma: ^2.0.0
+    lodash-es: ^4.17.21
+    mdast-util-from-markdown: ^1.3.0
+    non-layered-tidy-tree-layout: ^2.0.2
+    stylis: ^4.1.3
+    ts-dedent: ^2.2.0
+    uuid: ^9.0.0
+    web-worker: ^1.2.0
+  checksum: d8e4e4d7a0244da8f19d40b758ed39abdfd426c31a96196b4de991758954561da6056f038e0b4781f94c51bbc6a2a115370238f62250a3e6ba52d067174d7417
+  languageName: node
+  linkType: hard
+
 "methods@npm:~1.1.2":
  version: 1.1.2
  resolution: "methods@npm:1.1.2"
@@ -17600,6 +18169,13 @@ __metadata:
  languageName: node
  linkType: hard

+"non-layered-tidy-tree-layout@npm:^2.0.2":
+  version: 2.0.2
+  resolution: "non-layered-tidy-tree-layout@npm:2.0.2"
+  checksum: 73856e9959667193e733a7ef2b06a69421f4d9d7428a3982ce39763cd979a04eed0007f2afb3414afa3f6dc4dc6b5c850c2af9aa71a974475236a465093ec9c7
+  languageName: node
+  linkType: hard
+
 "nopt@npm:1.0.10":
  version: 1.0.10
  resolution: "nopt@npm:1.0.10"
@@ -20138,6 +20714,13 @@ __metadata:
  languageName: node
  linkType: hard

+"robust-predicates@npm:^3.0.0":
+  version: 3.0.2
+  resolution: "robust-predicates@npm:3.0.2"
+  checksum: 4ecd53649f1c2d49529c85518f2fa69ffb2f7a4453f7fd19c042421c7b4d76c3efb48bc1c740c8f7049346d7cb58cf08ee0c9adaae595cc23564d360adb1fde4
+  languageName: node
+  linkType: hard
+
 "rollup@npm:^2.74.1":
  version: 2.79.1
  resolution: "rollup@npm:2.79.1"
@@ -20189,6 +20772,13 @@ __metadata:
  languageName: node
  linkType: hard

+"rw@npm:1":
+  version: 1.3.3
+  resolution: "rw@npm:1.3.3"
+  checksum: b1e1ef37d1e79d9dc7050787866e30b6ddcb2625149276045c262c6b4d53075ddc35f387a856a8e76f0d0df59f4cd58fe24707e40797ebee66e542b840ed6a53
+  languageName: node
+  linkType: hard
+
 "rxjs@npm:^7.8.1":
  version: 7.8.1
  resolution: "rxjs@npm:7.8.1"
@@ -21020,6 +21610,13 @@ __metadata:
  languageName: node
  linkType: hard

+"stylis@npm:^4.1.3":
+  version: 4.3.0
+  resolution: "stylis@npm:4.3.0"
+  checksum: 5a9f7e0cf2a15591efaacc1c6416a8785d2b57522cd38bb8e0a81a03c23d3bea2363659fa5f9d486a73d1b6ebaf1d32826ce1c1974c95afdb5b495d98acb25c0
+  languageName: node
+  linkType: hard
+
 "sucrase@npm:^3.20.3, sucrase@npm:^3.32.0":
  version: 3.34.0
  resolution: "sucrase@npm:3.34.0"
@@ -21427,6 +22024,13 @@ __metadata:
  languageName: node
  linkType: hard

+"ts-dedent@npm:^2.2.0":
+  version: 2.2.0
+  resolution: "ts-dedent@npm:2.2.0"
+  checksum: 175adea838468cc2ff7d5e97f970dcb798bbcb623f29c6088cb21aa2880d207c5784be81ab1741f56b9ac37840cbaba0c0d79f7f8b67ffe61c02634cafa5c303
+  languageName: node
+  linkType: hard
+
 "ts-interface-checker@npm:^0.1.9":
  version: 0.1.13
  resolution: "ts-interface-checker@npm:0.1.13"
@@ -22368,6 +22972,15 @@ __metadata:
  languageName: node
  linkType: hard

+"uuid@npm:^9.0.0":
+  version: 9.0.1
+  resolution: "uuid@npm:9.0.1"
+  bin:
+    uuid: dist/bin/uuid
+  checksum: 1607dd32ac7fc22f2d8f77051e6a64845c9bce5cd3dd8aa0070c074ec73e666a1f63c7b4e0f4bf2bc8b9d59dc85a15e17807446d9d2b17c8485fbc2147b27f9b
+  languageName: node
+  linkType: hard
+
 "uvu@npm:^0.5.0":
  version: 0.5.6
  resolution: "uvu@npm:0.5.6"
@@ -22534,6 +23147,13 @@ __metadata:
  languageName: node
  linkType: hard

+"web-worker@npm:^1.2.0":
+  version: 1.2.0
+  resolution: "web-worker@npm:1.2.0"
+  checksum: 2bec036cd4784148e2f135207c62facf4457a0f2b205d6728013b9f0d7c62404dced95fcd849478387e10c8ae636d665600bd0d99d80b18c3bb2a7f045aa20d8
+  languageName: node
+  linkType: hard
+
 "webidl-conversions@npm:^3.0.0":
  version: 3.0.1
  resolution: "webidl-conversions@npm:3.0.1"