How to Create Mermaid Diagrams in VS Code | Application Flow, Architecture & SRE Workflows

In modern software engineering, understanding how applications, infrastructure, services, and teams interact is essential. Application Developers, Site Reliability Engineers (SREs), cloud engineers, and DevOps resources often need diagrams to explain application systems in a simple and understandable way.

Traditionally, software engineers create diagrams using tools that require manually placing shapes, drawing connections, and updating layouts whenever a system changes. This process can become more time-consuming, especially when documenting large cloud environments, application dependencies, incident management workflows, or organisational responsibilities.

1. What Is Mermaid.md?

Mermaid.md is a Markdown-based diagramming code that converts text definitions into visual diagrams. For example, consider a simple application workflow:

• A user opens an application.
• The application sends a request to a REST API and microservices.
• The API retrieves information from a database.
• The application returns a response to the user.
• Instead of manually drawing these components, you can describe the workflow using Mermaid code.

Sample Mermaid Markdown code and output visual diagram

sequenceDiagram

    autonumber

    actor User

    participant App as Veerpedia Application

    participant API as REST API Gateway

    participant MS as Microservices

    participant DB as Database

    User->>App: Open the application

    App->>API: Send API request

    API->>MS: Forward request

    MS->>DB: Retrieve information

    DB-->>MS: Return data

    MS-->>API: Return processed data

    API-->>App: Send API response

    App-->>User: Display response

    Note over User,App: User interacts with Veerpedia

    Note over API,DB: Backend processes the request

Output Visual Diagram

2. How to Preview Mermaid Diagrams in VS Code

After writing the Mermaid code in a notepad or text editor, you need to render it to confirm that the diagram looks correct. Before that, you need to save the file with a .md extension, and the file type should be Markdown. Once you save it accordingly, please follow the steps below

1. Open the .md file in VS Code.
2. Add your Mermaid code inside a fenced code block beginning with ```mermaid.
3. Save the file.
4. Open the Markdown preview using the preview command or the editor's preview icon.
5. Inspect the rendered diagram.
6. Update the source code if any nodes, connections, or labels need correction.

In supported VS Code versions, the built-in Markdown preview renders Mermaid diagrams directly. Larger diagrams can also be inspected using the preview's pan and zoom controls.

Note: Before you get started using VS Code for Mermaid code and diagrams, please make sure that you have installed the Mermaid extension in Visual Studio Code; refer to the extension snapshot given below.

How to Generate Mermaid Diagrams Using ChatGPT, Copilot, and VS Code

Step 1: Describe Your Requirement

Explain your application flow or architecture in simple English.

Step 2: Generate Mermaid Code Using ChatGPT

Prompt: Generate Mermaid code to visualise a web application flow involving a user, frontend, REST API, backend service, and database.

Step 3: Use GitHub Copilot

Open VS Code, ask Copilot to generate Mermaid code for your required application flow, cloud architecture, or SRE workflow.

Step 4: Create a Markdown File

Create `application-flow.md` and paste the generated code inside a Mermaid code block.

Step 5: Preview the Diagram

Open the Markdown preview in VS Code to visualise the diagram. If rendering is unavailable, check your VS Code version or use a suitable Mermaid extension.

Step 6: Refine and Validate

Ask ChatGPT or Copilot to add error paths, improve labels, or simplify the diagram. Verify the code and ensure the diagram accurately represents your system.